std::fpos

From cppreference.com
< cpplrm; | io
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>

In addition, std::u16streampos and std::u32streampos are provided as implementation-defined types that satisfy the requirements of pos_type in CharTraits

(since C++11)

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 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

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_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 or std::wstreampos).

Defect reports

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

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)
sets the output position indicator
(public member function of std::basic_ostream)
gets the file position indicator
(function)