public member function
<ostream> <iostream>
| (1) | basic_ostream& seekp (pos_type pos); |
|---|
| (2) | basic_ostream& seekp (off_type off, ios_base::seekdir way); |
|---|
Set position in output sequence
Sets the position where the next character is to be inserted into the output stream.
Internally, the function accesses the output sequence by first constructing a
sentry object without evaluating it. Then, if member
fail returns
true, the function returns.
Otherwise, it calls either
pubseekpos (1) or
pubseekoff (2) on its associated
stream buffer object (if any).
Finally, it destroys the
sentry object before returning.
Notice that the function will work even if the eofbit flag is set before the call, but it will not modify it.
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_ostream object (*this).
Errors are signaled by modifying the internal state flags:
| flag | error |
|---|
| eofbit | - |
| failbit | The internal call to pubseekpos in (1) failed (it may also be set if the construction of sentry failed).
|
| 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. |
| flag | error |
|---|
| eofbit | - |
| failbit | The internal call to either pubseekpos or pubseekoff failed (it may also be set if the construction of sentry failed).
|
| 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
|
// position in output stream
#include <fstream> // std::ofstream
int main () {
std::ofstream outfile;
outfile.open ("test.txt");
outfile.write ("This is an apple",16);
long pos = outfile.tellp();
outfile.seekp (pos-7);
outfile.write (" sam",4);
outfile.close();
return 0;
}
|
In this example, tellp is used to get the position in the stream after the writing operation. The pointer is then moved back 7 characters to modify the file at that position, so the final content of the file is:
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.