C++ streambuf::pubseekoff() function

The C++ std::streambuf::pubseekoff() function is used for seeking the specific position within a stream. It allows for repositioning the streams internal pointer relative to a given offset, which can be specified as an absolute or relative position.

This function returns the new position of the stream if successful, or std::streampos(-1) if an error occurred.

Syntax

Following is the syntax for std::streambuf::pubseekoff() function.

pos_type pubseekoff (off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);

Parameters

• off − It indicates the offset value.
• way − It indicates the object of type ios_base::seekdir.
• which − It is generally used to determine the position on which of the controlled sequence shall be modified.

Return Value

This function returns the new position value of the modified position pointer.

Exceptions

If an exception is thrown, the stream buffer is in a valid state.

Data races

It modifies the stream buffer object.

Example 1

Let's look at the following example, where we are going to seek to the beginning of the stream.

#include <iostream>
#include <sstream>
int main() {
   std::stringstream a("WELCOME");
   std::streambuf * b = a.rdbuf();
   b -> pubseekoff(0, std::ios::beg);
   std::cout << static_cast < char > (b -> sgetc()) << std::endl;
   return 0;
}

Output

Output of the above code is as follows −

W

Example 2

Consider the following example, where we are going to move the position 8 characters backward from the end and inserting welcome.

#include <iostream>
#include <sstream>
int main() {
   std::ostringstream a;
   a.str("Vanakam to TutorialsPoint");
   a.rdbuf() -> pubseekoff(-8, std::ios::end);
   a << "Welcome ";
   std::cout << "Result : " << a.str() << std::endl;
   return 0;
}

Output

Following is the output of the above code −

Result : Welcome to TutorialsPoint

Example 3

In the following example, we are going to seek the position beyond the stream length and observing the output.

#include <iostream>
#include <sstream>
int main() {
   std::stringstream a("Hi");
   std::streambuf * b = a.rdbuf();
   std::streampos c = b -> pubseekoff(5, std::ios::beg);
   if (c == std::streampos(-1)) {
      std::cout << "Invalid" << std::endl;
   } else {
      std::cout << "Result : " << c << std::endl;
   }
   return 0;
}

Output

If we run the above code it will generate the following output −

Invalid