public member function
<istream> <iostream>
| (1) | basic_istream& seekg (pos_type pos);
|
|---|
| (2) | basic_istream& seekg (off_type off, ios_base::seekdir way); |
|---|
Set position in input sequence
Sets the position of the next character to be extracted from the input stream.
Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to true). Then (if good), it calls either pubseekpos (1) or pubseekoff (2) on its associated stream buffer object (if any). Finally, it destroys the sentry object before returning.
If the
eofbit flag is set before the call, the function fails (sets
failbit and returns).
The function clears the
eofbit flag, if set before the call.
Calling this function does not alter the value returned by gcount.
Parameters
- pos
- New absolute position within the stream (relative to the beginning).
Member type pos_type is determined by the character traits: generally, it is an fpos type (such as streampos) that can be converted to/from integral types.
- off
- Offset value, relative to the way parameter.
Member type off_type is determined by the character traits: generally, it is an alias of the signed integral type streamoff.
- way
- Object of type ios_base::seekdir. It may take any of the following constant values:
| value | offset is relative to... |
|---|
| ios_base::beg | beginning of the stream |
| ios_base::cur | current position in the stream |
| ios_base::end | end of the stream |
Return Value
The basic_istream object (*this).
Errors are signaled by modifying the internal state flags:
| flag | error |
|---|
| eofbit | - |
| failbit | Either the construction of sentry failed, or the internal call to pubseekpos (1) or pubseekoff (2) failed (i.e., either function returned -1). |
| badbit | Another error occurred on the stream (such as when the function catches an exception thrown by an internal operation).
When set, the integrity of the stream may have been affected. |
Multiple flags may be set by a single operation.
If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
// read a file into memory
#include <iostream> // std::cout
#include <fstream> // std::ifstream
int main () {
std::ifstream is ("test.txt", std::ifstream::binary);
if (is) {
// get length of file:
is.seekg (0, is.end);
int length = is.tellg();
is.seekg (0, is.beg);
// allocate memory:
char * buffer = new char [length];
// read data as a block:
is.read (buffer,length);
is.close();
// print content:
std::cout.write (buffer,length);
delete[] buffer;
}
return 0;
}
|
In this example, seekg is used to move the position to the end of the file, and then back to the beginning.
Data races
Modifies the stream object.
Concurrent access to the same stream object may cause data races.
Exception safety
Basic guarantee: if an exception is thrown, the object is in a valid state.
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.