# 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 `n` th 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.

Revised 02 Feb 2008

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