std::fpos
| 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
| 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::fposconstructed in this manner is returned by some stream operations to indicate errors.
- Explicit conversion from (possibly const)
fposto std::streamoff. The result is the stored offset.
- operator== and operator!= that compare two objects of type (possibly const)
std::fposand 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.
- p + o has type
- 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::fposproducing 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_types 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 contradictionallyallowed 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
| represents relative file/stream position (offset from fpos), sufficient to represent any file size (typedef) | |
| returns the output position indicator (public member function of std::basic_ostream<CharT,Traits>) | |
| sets the output position indicator (public member function of std::basic_ostream<CharT,Traits>) | |
| gets the file position indicator (function) |