View source for cpp/io/fpos

{{cpp/title|fpos}}
{{cpp/io/navbar}}
{{dcl begin}}
{{dcl header|ios}}
{{dcl|1=
template< class State >
class fpos;
}}
{{dcl end}}

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

The following typedef names for {{c/core|std::fpos<std::mbstate_t>}} are provided (although they are spelled differently in the standard, they denote the same type): 

{{dsc begin}}
{{dsc header|iosfwd}}
{{dsc hitem|Type|Definition}}
{{dsc|{{tt|std::streampos}}|{{c/core|std::fpos<std::char_traits<char>::state_type>}}}}
{{dsc|{{tt|std::wstreampos}}|{{c/core|std::fpos<std::char_traits<wchar_t>::state_type>}}}}
{{dsc|{{tt|std::u8streampos}}{{mark c++20}}|{{c/core|std::fpos<std::char_traits<char8_t>::state_type>}}}}
{{dsc|{{tt|std::u16streampos}} {{mark c++11}}|{{c/core|std::fpos<std::char_traits<char16_t>::state_type>}}}}
{{dsc|{{tt|std::u32streampos}} {{mark c++11}}|{{c/core|std::fpos<std::char_traits<char32_t>::state_type>}}}}
{{dsc end}}

All specializations of {{tt|fpos}} meet the {{named req|DefaultConstructible}}, {{named req|CopyConstructible}}, {{named req|CopyAssignable}}, {{named req|Destructible}}, and {{named req|EqualityComparable}} requirements. 

If {{tt|State}} is trivially copy constructible, {{tt|fpos}} has a trivial copy constructor. 
If {{tt|State}} is trivially copy assignable, {{tt|fpos}} has a trivial copy assignment operator. 
If {{tt|State}} is trivially destructible, {{tt|fpos}} has a trivial destructor. 

===Template parameter===
{{par begin}}
{{par|State|the type representing the shift state}}
{{par hreq}}
{{par req named|State|DefaultConstructible|CopyConstructible|CopyAssignable|Destructible}}
{{par end}}

===Member functions===
{{dsc begin}}
{{dsc mem fun|cpp/io/fpos/state|gets/sets the value of the shift state}}
{{dsc end}}

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) {{lc|std::streamoff}}, which stores that offset and value-initializes the state object. This constructor must also accept the special value {{c|std::streamoff(-1)}}: the {{tt|std::fpos}} constructed in this manner is returned by some stream operations to indicate errors.

* Explicit conversion from (possibly const) {{tt|fpos}} to {{lc|std::streamoff}}. The result is the stored offset.

* {{c/core|1=operator==}} and {{c/core|1=operator!=}} that compare two objects of type (possibly const) {{tt|std::fpos}} and return a {{c/core|bool}} prvalue. {{c|1=p != q}} is equivalent to {{c|1=!(p == q)}}.

* {{c/core|operator+}} and {{c/core|operator-}} such that, for an object {{c|p}} of type (possibly const) {{tt|fpos<State>}} and an object {{c|o}} of type (possibly const) {{lc|std::streamoff}}
:* {{c|p + o}} has type {{tt|fpos<State>}} and stores an offset that is the result of adding {{c|o}} to the offset of {{c|p}}.
:* {{c|o + p}} has a type convertible to {{tt|fpos<State>}} and the result of the conversion is equal to {{c|p + o}}.
:* {{c|p - o}} has type {{tt|fpos<State>}} and stores an offset that is the result of subtracting {{c|o}} from the offset of {{c|p}}.

* {{c/core|1=operator+=}} and {{c/core|1=operator-=}} which can accept a (possibly const) {{lc|std::streamoff}} and adds/subtracts it from the stored offset, respectively.

* {{c/core|operator-}} which can subtract two objects of type (possibly const) {{tt|std::fpos}} producing an {{lc|std::streamoff}}, such that for two such objects {{c|p}} and {{c|q}}, {{c|1=p == q + (p - q)}}.

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

=== Defect reports ===
{{dr list begin}}
{{dr list item|wg=lwg|dr=57|std=C++98|before={{tt|streampos}} and {{tt|wstreampos}} were contradictionally<br>allowed to be different while required to be the same|after=clarified to<br>be the same}}
{{dr list item|paper=P0759R1|std=C++98|before=specification was unclear and incomplete|after=cleaned up}}
{{dr list item|paper=P1148R0|std=C++11|before=unclear what and in which header the<br>definitions {{tt|u16streampos}} and {{tt|u32streampos}} are|after=made clear}}
{{dr list item|wg=lwg|dr=2114|paper=P2167R3|std=C++98|before=non-{{c/core|bool}} return types of equality comparisons were allowed|after=disallowed}}
{{dr list end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/io/dsc streamoff}}
{{dsc inc|cpp/io/basic_ostream/dsc tellp}}
{{dsc inc|cpp/io/basic_ostream/dsc seekp}}
{{dsc inc|cpp/io/c/dsc fgetpos}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pt|ru|zh}}