no copyright!fpos.3

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

type object
streamsize sz
streamoff o
fpos<stateT> p, q
int i

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)
Copyright © 1999 Dietmar Kühl, Claas Solutions (dietmar.kuehl@claas-solutions.de)