std::basic_ostream::seekp(3)

💖 NAME

std::basic_ostream::seekp — okay bestie, this is the function that sets the output position indicator, and it is lowkey iconic. Manual name drop: C++ Standard Libary (yes, that spelling is in the source, we respect the lore), and the page is std::basic_ostream::seekp(3).

🌸 SYNOPSIS

basic_ostream& seekp( pos_type pos );                             (1)
basic_ostream& seekp( off_type off, std::ios_base::seekdir dir ); (2)

Sets the output position indicator of the current associated streambuf object.

Behaves as UnformattedOutputFunction (except, since C++11, without actually performing output). After constructing and checking the sentry object:

1. if fail() != true, sets the output position indicator to absolute (relative to the beginning of the file) value pos by calling rdbuf()->pubseekpos(pos, std::ios_base::out). In case of failure, calls setstate(std::ios_base::failbit).
2. if fail() != true, sets the output position indicator to offset off relative to dir by calling rdbuf()->pubseekoff(off, dir, std::ios_base::out). In case of failure, calls setstate(std::ios_base::failbit).

✨ PARAMETERS

• pos — absolute position to set the output position indicator to.
• off — relative position (positive or negative) to set the output position indicator to.
• dir — defines the base position to apply the relative offset to. It can be one of the following constants:
  • beg — the beginning of a stream
  • end — the ending of a stream
  • cur — the current position of stream position indicator

🫶 RETURN VALUE

*this — she said “I’m the main character” and returned herself.

😭 EXCEPTIONS

1,2) May throw std::ios_base::failure in case of failure, if exceptions() & failbit != 0.

🎀 EXAMPLE

// Run this code

#include <iostream>
#include <sstream>

int main()
{
    std::ostringstream os("hello, world");
    os.seekp(7);
    os << 'W';
    os.seekp(0, std::ios_base::end);
    os << '!';
    os.seekp(0);
    os << 'H';
    std::cout << os.str() << '\n';
}

🌈 OUTPUT

Hello, World!

🧚 DEFECT REPORTS

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

Table columns, for the record: DR, Applied to, Behavior as published, Correct behavior.

• LWG 129 — applied to C++98. Behavior as published: there was no way to indicate a failure. Correct behavior: sets failbit on failure.
• LWG 136 — applied to C++98. Behavior as published: seekp could set the input stream. Correct behavior: only sets the output stream.
• LWG 537 — applied to C++98. Behavior as published: 1. the type of pos was pos_type&; 2. the type of off was off_type&. Correct behavior: 1. corrected to pos_type; 2. corrected to off_type.
• LWG 2341 — applied to C++98. Behavior as published: the resolution of LWG issue 129 for overload (2) was removed. Correct behavior: restored.

👑 SEE ALSO

• tellp — returns the output position indicator (public member function)
• tellg — returns the input position indicator (public member function of std::basic_istream<CharT,Traits>)
• seekg — sets the input position indicator (public member function of std::basic_istream<CharT,Traits>)

source: http://cppreference.com · version/date: 2024.06.10 · page: std::basic_ostream::seekp(3) — that’s the whole vibe, mwah 💋✨