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

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>::type`	semantics
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:

If T is a standard stream or stream buffer type, delegates to std::basic_streambuf::pubseekoff or std::basic_streambuf::pubseekpos, as appropriate.
Otherwise, if the mode of T allows only one reading head, delegates to a member function seek which takes a stream_offset and a seekdir but no openmode.
Otherwise, if the mode of T allows random access with two reading heads, delegates to a member function seek which takes a stream_offset, a seekdir and an openmode.
If the mode of T does not permit random access, attempting to invoke seek is a compile-time error.

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Function Template seek