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 specializations of std::fpos
are provided:
Type | Definition |
---|---|
streampos | std::fpos<std::char_traits<char>::state_type> |
wstreampos | std::fpos<std::char_traits<wchar_t>::state_type> |
u8streampos (since C++20) | std::fpos<std::char_traits<char8_t>::state_type> |
u16streampos (since C++11) | std::fpos<std::char_traits<char16_t>::state_type> |
u32streampos (since 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.
State | - | the type representing the shift state |
Type requirements | ||
-State must meet the requirements of Destructible, CopyAssignable, CopyConstructible and DefaultConstructible. |
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:
std::streamoff
, which stores that offset and 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. fpos
to std::streamoff
. The result is the stored offset. operator==
and operator!=
that compare two objects of type (possibly const) std::fpos
and returns a value of type convertible to bool
. 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)
std::streampos
and std::wstreampos
are required to be the same type because std::char_traits<char>::state_type
and std::char_traits<wchar_t>::state_type
are required to both be std::mbstate_t
. C++98 had a self-contradictory statement that they may be different if the implementation supports no shift encoding in narrow-oriented iostreams but supports one or more shift encodings in wide-oriented streams, but that was corrected in C++03.
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
or std::wstreampos
).
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
P0759R1 | C++98 | specification was unclear and incomplete | cleaned up |
P1148R0 | C++11 | unclear what header defines u16streampos and u32streampos or what their definitions are | made clear |
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) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/io/fpos