Template Class fpos
Synopsis
|
#include <ios>
namesapace std {
template <class stateT>
class fpos {
public:
stateT state() const;
void state(stateT s);
};
}
|
Description
The class fpos is used to store positions in a stream. These
positions may consist of a position in the underlying external
representation and a corresponding conversion state: When the external
character representation differs from the internal representation,
as is e.g. the case if the external representation uses a multi-byte
encoding, a position in a stream cannot always be represented just as
the offset from the beginning but might also depend on a conversion
state ("shift state") which describes how the next character has
to be interpreted.
The type fpos is not directly used in the interface of the stream
classes: The stream classes are templatized with a character type and
a type which describes the traits of this character type. This traits
defaults to char_type<charT> where
code charT is the character type. The member pos_type
of the traits class used for a stream is used to represent positions
in a stream. For the two standard specializations
char_traits<char> and
char_traits<wchar_t> the
member pos_type is defined
to be fpos<mbstate_t>.
Although it is possible to construct fpos<stateT> objects from
ints or from objects of type
streamoff, these positions
cannot be used as seek positions for
streams. This is because these position objects don't known anything
about the corresponding conversion state. However, position objects
constructed from int or streamoff can be used to compare with
other position objects: Comparing stream positions ignores the conversion
state. In particular, the value
fpos<stateT>(streamoff(-1))
is used to indicate an invalid position. This value is returned by functions
returning stream positions to indicate an error.
Requirements for std::fpos<stateT>
The following two tables list the requirements imposed on the
implementation of fpos<stateT>.
expression |
return type |
semantic |
fpos<stateT>(i) |
fpos<stateT> |
The new fpos<stateT> object represents the position
i characters from the beginning of a stream. |
fpos<stateT>(o) |
fpos<stateT> |
The new fpos<stateT> object represents the position
o characters from the beginning of a stream. |
p == q |
Convertible to bool |
Yields true if p
and q represent identical positions. == is an equivalence
relation. |
p != q |
Convertible to bool |
Yields true if p
and q represent different positions. |
p += o |
fpos<stateT> |
p is moved by o
characters. |
p -= o |
fpos<stateT> |
p is moved by -o
characters. |
q = p + o |
fpos<stateT> |
The difference between q
and p is o characters. |
q = p - o |
fpos<stateT> |
The difference between q
and p is -o characters. |
o = p - q |
streamoff |
o represents the number of characters between p and q. |
streamoff(sz) |
streamoff |
The streamoff object
represents an offset of sz characters. |
streamoff(p) |
streamoff |
The streamoff object
represents the number of characters between p and the beginning
of the stream. |
streamsize(o) |
streamsize |
Conversion to streamsize. |
Member Functions
fpos<stateT>::state() const
This member function returns the conversion state stored with the
object.
fpos<stateT>::state(stateT s)
This member function stores s as the conversion state
with the object.
See Also
char_traits(3),
iostream-types(3),
basic_streambuf(3)