home | help 
std::basic_...buf::seekoff(3)  C++ Standard Libary std::basic_...buf::seekoff(3)

NAME
     std::basic_filebuf::seekoff - std::basic_filebuf::seekoff

Synopsis
	protected:

	virtual pos_type seekoff( off_type off,
				  std::ios_base::seekdir dir,

				  std::ios_base::openmode	  which        =
     std::ios_base::in |
	std::ios_base::out );

	Repositions the file pointer, if possible, to the position  that  corre-
     sponds to
	exactly  off  characters from beginning, end, or current position of the
     file
	(depending on the value of dir).

	If the associated file is not open (is_open() == false),  fails  immedi-
     ately.

	If  the multibyte character encoding is state-dependent (codecvt::encod-
     ing() returned
	-1) or variable-length (codecvt::encoding() returned 0) and  the  offset
     off is not 0,
	fails  immediately:  this  function cannot determine the number of bytes
     that
	correspond to off characters.

	If dir is not std::basic_ios::cur or the offset off is not  0,	and  the
     most recent
	operation  done  on  this filebuf object was output (that is, either the
     put buffer is
	not empty, or the most recently called function  was  overflow()),  then
     calls
	std::codecvt::unshift  to  determine the unshift sequence necessary, and
     writes that
	sequence to the file by calling overflow().

	Then converts the argument dir to a value whence of type int as follows:

	value of dir	    value of whence
	std::basic_ios::beg SEEK_SET
	std::basic_ios::end SEEK_END
	std::basic_ios::cur SEEK_CUR

	Then, if the character encoding is fixed-width (codecvt::encoding()  re-
     turns some
	positive number width), moves the file pointer as if by std::fseek(file,
     width*off,
	whence).

	Otherwise, moves the file pointer as if by std::fseek(file, 0, whence).

	The openmode argument, required by the base class function signature, is
     usually
	ignored, because std::basic_filebuf maintains only one file position.

Parameters
	off   - relative position to set the position indicator to
		defines base position to apply the relative offset to. It can be
     one of the
		following constants:

	dir   - Constant Explanation
		beg	 the beginning of a stream
		end	 the ending of a stream
		cur	 the current position of stream position indicator
		defines which of the input and/or output sequences to affect. It
     can be one
		or a combination of the following constants:
	which -
		Constant Explanation
		in	 affect the input sequence
		out	 affect the output sequence

Return value
	A  newly  constructed object of type pos_type which stores the resulting
     file
	position, or pos_type(off_type(-1)) on failure.

Notes
	seekoff() is called by std::basic_streambuf::pubseekoff, which is called
     by
	std::basic_istream::seekg,	std::basic_ostream::seekp,	std::ba-
     sic_istream::tellg, and
	std::basic_ostream::tellp.

Example
     // Run this code

      #include <fstream>
      #include <iostream>
      #include <locale>

      template<typename CharT>
      int get_encoding(const std::basic_istream<CharT>& stream)
      {
	  using Facet = std::codecvt<CharT, char, std::mbstate_t>;
	  return std::use_facet<Facet>(stream.getloc()).encoding();
      }

      int main()
      {
	  //  prepare a 10-byte file holding 4 characters ("zAae<degree>'dh") in
     UTF-8
	  std::ofstream("text.txt")					      <<
     "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";

	  // open using a non-converting encoding
	  std::ifstream f1("text.txt");
	  std::cout << "f1's locale's encoding() returns "
		    << get_encoding(f1) << '\n'
		    << "pubseekoff(3, beg) returns "
		    << f1.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\n'
		    << "pubseekoff(0, end) returns "
		    << f1.rdbuf()->pubseekoff(0, std::ios_base::end) << '\n';

	  // open using UTF-8
	  std::wifstream f2("text.txt");
	  f2.imbue(std::locale("en_US.UTF-8"));
	  std::cout << "f2's locale's encoding() returns "
		    << get_encoding(f2) << '\n'
		    << "pubseekoff(3, beg) returns "
		    << f2.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\n'
		    << "pubseekoff(0, end) returns "
		    << f2.rdbuf()->pubseekoff(0, std::ios_base::end) << '\n';
      }

Output:
      f1's locale's encoding() returns 1
      pubseekoff(3, beg) returns 3
      pubseekoff(0, end) returns 10
      f2's locale's encoding() returns 0
      pubseekoff(3, beg) returns -1
      pubseekoff(0, end) returns 10

	Defect reports

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

	  DR   Applied to	Behavior as published		Correct behavior
	LWG	55     C++98	      seekoff	  returned     an      undefined
     pos_type(off_type(-1))
			  invalid  stream  position  on  failure  is returned on
     failure

See also
	pubseekoff invokes seekoff()
		   (public     member	  function     of     std::basic_stream-
     buf<CharT,Traits>)
	seekpos    repositions the file position, using absolute addressing
	[virtual]  (virtual protected member function)
	fseek	   moves the file position indicator to a specific location in a
     file
		   (function)

http://cppreference.com 	   2024.06.10	   std::basic_...buf::seekoff(3)
home | help