The latest version of this topic can be found at fpos Class.
The template class describes an object that can store all the information needed to restore an arbitrary file-position indicator within any stream. An object of class fpos< St> effectively stores at least two member objects:
A byte offset, of type streamoff.
A conversion state, for use by an object of class basic_filebuf, of type St, typically
mbstate_t.
It can also store an arbitrary file position, for use by an object of class basic_filebuf, of type fpos_t. For an environment with limited file size, however, streamoff and fpos_t may sometimes be used interchangeably. For an environment with no streams that have a state-dependent encoding, mbstate_t may actually be unused. Therefore, the number of member objects stored may vary.
Syntax
template <class Statetype>
class fpos
Parameters
Statetype
State information.
Constructors
| fpos | Create an object that contains information about a position (offset) in a stream. |
Member Functions
| seekpos | Used internally by the Standard C++ Library only. Do not call this method from your code. |
| state | Sets or returns the conversion state. |
Operators
| operator!= | Tests file-position indicators for inequality. |
| operator+ | Increments a file-position indicator. |
| operator+= | Increments a file-position indicator. |
| operator- | Decrements a file-position indicator. |
| operator-= | Decrements a file-position indicator. |
| operator== | Tests file-position indicators for equality. |
| operator streamoff | Casts object of type fpos to object of type streamoff. |
Requirements
Header: <ios>
Namespace: std
fpos::fpos
Create an object that contains information about a position (offset) in a stream.
fpos(streamoff _Off =0);
fpos(Statetype _State, fpos_t _Filepos);
Parameters
_Off
The offset into the stream.
_State
The starting state of the fpos object.
_Filepos
The offset into the stream.
Remarks
The first constructor stores the offset _Off, relative to the beginning of file and in the initial conversion state (if that matters). If _Off is -1, the resulting object represents an invalid stream position.
The second constructor stores a zero offset and the object _State.
fpos::operator!=
Tests file-position indicators for inequality.
bool operator!=(const fpos<Statetype>& right) const;
Parameters
right
The file-position indicator against which to compare.
Return Value
true if the file-position indicators are not equal, otherwise false.
Remarks
The member function returns !( *this == right).
Example
// fpos_op_neq.cpp
// compile with: /EHsc
#include <fstream>
#include <iostream>
int main( )
{
using namespace std;
fpos<int> pos1, pos2;
ifstream file;
char c;
// Compare two fpos object
if ( pos1 != pos2 )
cout << "File position pos1 and pos2 are not equal" << endl;
else
cout << "File position pos1 and pos2 are equal" << endl;
file.open( "fpos_op_neq.txt" );
file.seekg( 0 ); // Goes to a zero-based position in the file
pos1 = file.tellg( );
file.get( c);
cout << c << endl;
// Increment pos1
pos1 += 1;
file.get( c );
cout << c << endl;
pos1 = file.tellg( ) - fpos<int>( 2);
file.seekg( pos1 );
file.get( c );
cout << c << endl;
// Increment pos1
pos1 = pos1 + fpos<int>( 1 );
file.get(c);
cout << c << endl;
pos1 -= fpos<int>( 2 );
file.seekg( pos1 );
file.get( c );
cout << c << endl;
file.close( );
}
fpos::operator+
Increments a file-position indicator.
fpos<Statetype> operator+(streamoff _Off) const;
Parameters
_Off
The offset by which you want to increment the file-position indicator.
Return Value
The position in the file.
Remarks
The member function returns fpos(*this) += _Off.
Example
See operator!= for a sample of using operator+.
fpos::operator+=
Increments a file-position indicator.
fpos<Statetype>& operator+=(streamoff _Off);
Parameters
_Off
The offset by which you want to increment the file-position indicator.
Return Value
The position in the file.
Remarks
The member function adds _Off to the stored offset member object and then returns *this. For positioning within a file, the result is generally valid only for binary streams that do not have a state-dependent encoding.
Example
See operator!= for a sample of using operator+=.
fpos::operator-
Decrements a file-position indicator.
streamoff operator-(const fpos<Statetype>& right) const;
fpos<Statetype> operator-(streamoff _Off) const;
Parameters
right
File position.
_Off
Stream offset.
Return Value
The first member function returns (streamoff)*this - (streamoff)right. The second member function returns fpos(*this) -= _Off.
Example
See operator!= for a sample of using operator-.
fpos::operator-=
Decrements a file-position indicator.
fpos<Statetype>& operator-=(streamoff _Off);
Parameters
_Off
Stream offset.
Return Value
The member function returns fpos(*this) -= _Off.
Remarks
For positioning within a file, the result is generally valid only for binary streams that do not have a state-dependent encoding.
Example
See operator!= for a sample of using operator-=.
fpos::operator==
Tests file-position indicators for equality.
bool operator==(const fpos<Statetype>& right) const;
Parameters
right
The file-position indicator against which to compare.
Return Value
true if the file-position indicators are equal; otherwise false.
Remarks
The member function returns (streamoff)*this == (streamoff)right.
Example
See operator!= for a sample of using operator+=.
fpos::operator streamoff
Cast object of type fpos to object of type streamoff.
operator streamoff() const;
Remarks
The member function returns the stored offset member object and any additional offset stored as part of the fpos_t member object.
Example
// fpos_op_streampos.cpp
// compile with: /EHsc
#include <ios>
#include <iostream>
#include <fstream>
int main( )
{
using namespace std;
streamoff s;
ofstream file( "rdbuf.txt");
fpos<mbstate_t> f = file.tellp( );
// Is equivalent to ..
// streampos f = file.tellp( );
s = f;
cout << s << endl;
}
0
fpos::seekpos
This method is used internally by the Standard C++ Library only. Do not call this method from your code.
fpos_t seekpos() const;
fpos::state
Sets or returns the conversion state.
Statetype state() const;
void state(Statetype _State);
Parameters
_State
The new conversion state.
Return Value
The conversion state.
Remarks
The first member function returns the value stored in the St member object. The second member function stores _State in the St member object.
Example
// fpos_state.cpp
// compile with: /EHsc
#include <ios>
#include <iostream>
#include <fstream>
int main() {
using namespace std;
streamoff s;
ifstream file( "fpos_state.txt" );
fpos<mbstate_t> f = file.tellg( );
char ch;
while ( !file.eof( ) )
file.get( ch );
s = f;
cout << f.state( ) << endl;
f.state( 9 );
cout << f.state( ) << endl;
}
See Also
Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions