Function Template seek

Overview
Headers
Reference

Overview

The function template seek is used by the Iostreams library to perform random access withing a sequence controlled by a Device.

Headers

<boost/iostreams/operations.hpp>
<boost/iostreams/seek.hpp>

Reference

Description

Repositions one or both heads within the sequence controlled by a given instance of the template parameter T, returning the resulting stream position.

Synopsis

namespace boost { namespace iostreams {
              
template<typename T>
std::streampos 
seek( T&, stream_offset  off, std::ios_base::seekdir way,
      std::ios_base::openmode which =
          std::ios_base::in | std::ios_base::out );

} } // End namespace boost::io

Template Parameters

T- A model of one of the Device concepts which allows random access.

Function Parameters

off- A stream_offset indicating the number of characters by which the appropriate reading or writing heads should be advanced. The initial position is determined by the parameter way.
way-

Determines the initial position to which the offset off is applied, as follows:

  • if way is std::ios_base::beg, the initial position is the begining of the stream
  • if way is std::ios_base::cur, the initial position is the current position
  • if way is std::ios_base::end, the initial position is the end of the stream

which- Determines whether the reading head, the writing head or both are repositioned.

Semantics

The semantics of seek depends on the category of T as follows:

category_of<T>::typesemantics
convertible to istream_tag or ostream_tag returns:
  • t.rdbuf()->pubseekpos(offset_to_position(off)), if way is std::ios_base::beg and off is outside the range of std::streamoff, and
  • t.rdbuf()->pubseekoff(off, way), otherwise
convertible to streambuf_tag returns:
  • t.pubseekpos(offset_to_position(off)), if way is std::ios_base::beg and off is outside the range of std::streamoff, and
  • t.pubseekoff(off, way), otherwise
convertible to input_seekable but not to output_seekable returns t.seek(off, way)
convertible to output_seekable but not to input_seekable returns t.seek(off, way)
convertible to dual_seekable or to bidirectional_seekable returns t.seek(off, way, which)
convertible to seekable returns t.seek(off, way)
otherwise compile-time error

In short: