Stream Offsets

Overview
Acknowledgments
Headers
Reference

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

namespace boost { namespace iostreams {

typedef boost::intmax_t stream_offset;
std::streampos offset_to_position(stream_offset n);
stream_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.