Function Template seek

OverviewHeadersReference

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

namespaceboost {namespaceiostreams {template<typename[T](#template_params)>
std::streampos[seek](#semantics)( T&,[stream\_offset](positioning.html#synopsis)[off](#function_params), std::ios_base::seekdir[way](#function_params),
      std::ios_base::openmode[which](#function_params)=
          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:

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

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

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)