NAME¶

std::fpos - std::fpos

Synopsis¶

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
streampos std::fpos<std::char_traits<char>::state_type>
wstreampos std::fpos<std::char_traits<wchar_t>::state_type>
u8streampos (C++20) std::fpos<std::char_traits<char8_t>::state_type>
u16streampos (C++11) std::fpos<std::char_traits<char16_t>::state_type>
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 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 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)

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
streampos and wstreampos were
LWG 57 C++98 contradictionally allowed to be different clarified to be same
whiled required to be same
P0759R1 C++98 specification was unclear and incomplete cleaned up
P1148R0 C++11 unclear what and in which header the made clear
definition u16streampos and u32streampos are

See also¶

represents relative file/stream position (offset from fpos), sufficient to
streamoff represent any file size
(typedef)
tellp returns the output position indicator
(public member function of std::basic_ostream<CharT,Traits>)
seekp sets the output position indicator
(public member function of std::basic_ostream<CharT,Traits>)
fgetpos gets the file position indicator
(function)