# std::fpos

> C++ Atlas: `cppatlas.com/w/cpp/io/fpos` | Source: https://en.cppreference.com/w/cpp/io/fpos | Domain: Input/output | Standards: C++11, C++20

Specializations of the class template std::fpos identify absolute positions in a stream or in a file.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <ios>

template< class State >
class fpos;
```

Specializations of the class template `std::fpos` identify absolute positions in a stream or in a file. Each object of type `fpos` holds the byte position in the stream (typically as a private member of type `std::streamoff`) and the current shift state, a value of type `State` (typically `std::mbstate_t`).

The following typedef names for `std::fpos<std::mbstate_t>` are provided (although they are spelled differently in the standard, they denote the same type):

Defined in header `<iosfwd>`

**Type — Definition**

- `std::streampos`: `std::fpos<std::char_traits<char>::state_type>`
- `std::wstreampos`: `std::fpos<std::char_traits<wchar_t>::state_type>`
- `std::u8streampos` (C++20): `std::fpos<std::char_traits<char8_t>::state_type>`
- `std::u16streampos` (C++11): `std::fpos<std::char_traits<char16_t>::state_type>`
- `std::u32streampos` (C++11): `std::fpos<std::char_traits<char32_t>::state_type>`

All specializations of `fpos` meet the *DefaultConstructible*, *CopyConstructible*, *CopyAssignable*, *Destructible*, and *EqualityComparable* requirements.

If `State` is trivially copy constructible, `fpos` has a trivial copy constructor. If `State` is trivially copy assignable, `fpos` has a trivial copy assignment operator. If `State` is trivially destructible, `fpos` has a trivial destructor.

### Template parameter

- `State` - the type representing the shift state

**Type requirements**

- `State` must meet the requirements of *Destructible*, *CopyAssignable*, *CopyConstructible* and *DefaultConstructible*.

### Member functions

- `state`: gets/sets the value of the shift state (public member function)

In addition, member and non-member functions are provided to support the following operations:

- A default constructor that stores an offset of zero and value-initializes the state object.

- A non-explicit constructor that accepts an argument of type (possibly const) `std::streamoff`, which stores that offset and value-initializes the state object. This constructor must also accept the special value `std::streamoff(-1)`: the `std::fpos` constructed in this manner is returned by some stream operations to indicate errors.

- Explicit conversion from (possibly const) `fpos` to `std::streamoff`. The result is the stored offset.

- `operator==` and `operator!=` that compare two objects of type (possibly const) `std::fpos` and return a `bool` prvalue. `p != q` is equivalent to `!(p == q)`.

- `operator+` and `operator-` such that, for an object `p` of type (possibly const) `fpos<State>` and an object `o` of type (possibly const) `std::streamoff`

  - `p + o` has type `fpos<State>` and stores an offset that is the result of adding `o` to the offset of `p`.
  - `o + p` has a type convertible to `fpos<State>` and the result of the conversion is equal to `p + o`.
  - `p - o` has type `fpos<State>` and stores an offset that is the result of subtracting `o` from the offset of `p`.

- `operator+=` and `operator-=` which can accept a (possibly const) `std::streamoff` and adds/subtracts it from the stored offset, respectively.

- `operator-` which can subtract two objects of type (possibly const) `std::fpos` producing an `std::streamoff`, such that for two such objects `p` and `q`, `p == q + (p - q)`.

### Notes

Some of the I/O streams member functions return and manipulate objects of member typedef `pos_type`. For streams, these member typedefs are provided by the template parameter `Traits`, which defaults to `std::char_traits`, which define their `pos_type`s to be specializations of `std::fpos`. The behavior of the I/O streams library is implementation-defined when `Traits::pos_type` is not `std::fpos<std::mbstate_t>` (aka `std::streampos`, `std::wstreampos`, etc.).

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 57 | C++98 | `streampos` and `wstreampos` were contradictionally allowed to be different while required to be the same | clarified to be the same |
| P0759R1 | C++98 | specification was unclear and incomplete | cleaned up |
| P1148R0 | C++11 | unclear what and in which header the definitions `u16streampos` and `u32streampos` are | made clear |
| LWG 2114 (P2167R3) | C++98 | non-`bool` return types of equality comparisons were allowed | disallowed |

### See also

- [`streamoff`](https://en.cppreference.com/w/cpp/io/streamoff): represents relative file/stream position (offset from fpos), sufficient to represent any file size (typedef)
- [`tellp`](https://en.cppreference.com/w/cpp/io/basic_ostream/tellp): returns the output position indicator (public member function of `std::basic_ostream<CharT,Traits>`)
- [`seekp`](https://en.cppreference.com/w/cpp/io/basic_ostream/seekp): sets the output position indicator (public member function of `std::basic_ostream<CharT,Traits>`)
- [`fgetpos`](https://en.cppreference.com/w/cpp/io/c/fgetpos): gets the file position indicator (function)

---
Attribution: content from https://en.cppreference.com/w/cpp/io/fpos (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.