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 or by a standard stream or stream buffer. seek is designed to be overloaded or specialized for Device types external to the Iostreams Library. The default implementation, however, should be suitable for most purposes.

Note: Unlike read and write, seek has no overload for Filter types. Filters which perform random access are required to have a member function seek.

Headers

<boost/iostreams/operations.hpp>

Reference

Description

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

Synopsis

namespace boost { namespace iostreams {
              
template<typename T>
std::streamoff seek( T&, std::streamoff 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, or a standard stream or stream buffer type.

Function Parameters

off - A std::streamoff value 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::beg, 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:

`io_category<T>::type`	semantics
convertible to `istream_tag` or `ostream_tag`	returns `t.rdbuf()->pubseekoff(off, way)`
convertible to `streambuf_tag`	returns `t.pubseekoff(off, way)`
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.
Otherwise, if the i/o mode of T allows only one reading head, delegates to a member function seek which takes a streamoff and a seekdir but no openmode.
Otherwise, if the i/o mode of T allows random access with two reading heads, delegates to a member function seek which takes a streamoff, a seekdir and an openmode.
If the i/o mode of T does not permit random access, attempting to invoke seek is a compile-time error.

Revised 20 May, 2004

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