Stream Offsets

OverviewAcknowledgmentsHeadersReference

Overview

The header <boost/iostreams/positioning.hpp> provides the definition of the integral type boost::iostreams::stream_offset, capable of holding arbitrary stream offsets on most platforms, together with the definition of two functions, offset_to_position and position_to_offset, for converting between stream_offset and std::streampos.

The type std::streampos is required to be able to hold an arbitrary stream position, but it is not an intergral type. Although std::streampos is interconvertible with the integral type std::streamoff, the conversion from std::streampos to std::streamoff may not be faithful for large (64-bit) values. The integral type boost::iostreams::stream_offset is intended as a replacement for std::streamoff, with the implicit conversions to and from std::streampos being replaced by explicit conversion functions.

The implementation of offset_to_position and position_to_offset relies on implementation defined behavior, and is guaranteed to work correctly for large values only for standard libraries which define std::streamoff to be 64-bit type or for which the Boost Iostreams library has been explicitly configured.

Acknowledgments

Gareth Sylvester-Bradley suggested the treatment of large stream offsets used by the Boost Iostreams library and supplied the implementation of offset_to_position and position_to_offset used with the Dinkumware standard library.

Headers

<boost/iostreams/positioning.hpp>

Reference

Synopsis

namespaceboost {namespaceiostreams {typedef[boost::intmax\_t](../../../integer/doc/html/boost_integer/cstdint.html)stream_offset;
std::streampos[offset\_to\_position](#offset_to_position)(stream_offset n);
stream_offset[position\_to\_offset](#position_to_offset)(std::streampos pos);

} }// End namespace boost::io

Function template offset_to_position

std::streampos offset_to_position(stream_offset n);

Returns a std::streampos representing the nth position in a stream.

Function template position_to_offset

stream_offset position_to_offset(std::streampos pos);

Returns a stream_offset representing the same character position as pos, disregarding any code-conversion state.

© 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)