# 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::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:

`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.

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 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)