1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Stream Offsets
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Stream Offsets
</H1>
17 <DL class=
"page-index">
18 <DT><A href=
"#overview">Overview
</A></DT>
19 <DT><A href=
"#acknowledgments">Acknowledgments
</A>
20 <DT><A href=
"#headers">Headers
</A></DT>
21 <DT><A href=
"#reference">Reference
</A></DT>
26 <A NAME=
"overview"></A>
30 The header
<A CLASS=
"header" HREF=
"../../../../boost/iostreams/positioning.hpp"><CODE><boost/iostreams/positioning.hpp
></CODE></A> provides the definition of the integral type
<CODE>boost::iostreams::stream_offset
</CODE>, capable of holding arbitrary stream offsets on most platforms, together with the definition of two functions,
<CODE>offset_to_position
</CODE> and
<CODE>position_to_offset
</CODE>, for converting between
<CODE>stream_offset
</CODE> and
<CODE>std::streampos
</CODE>.
34 The type
<CODE>std::streampos
</CODE> is required to be able to hold an arbitrary stream position, but it is not an intergral type. Although
<CODE>std::streampos
</CODE> is interconvertible with the integral type
<CODE>std::streamoff
</CODE>, the conversion from
<CODE>std::streampos
</CODE> to
<CODE>std::streamoff
</CODE> may not be faithful for large (
64-bit) values. The integral type
<CODE>boost::iostreams::stream_offset
</CODE> is intended as a replacement for
<CODE>std::streamoff
</CODE>, with the implicit conversions to and from
<CODE>std::streampos
</CODE> being replaced by explicit conversion functions.
38 The implementation of
<CODE>offset_to_position
</CODE> and
<CODE>position_to_offset
</CODE> relies on implementation defined behavior, and is guaranteed to work correctly for large values only for standard libraries which define
<CODE>std::streamoff
</CODE> to be
64-bit type or for which the Boost Iostreams library has been explicitly configured.
41 <A NAME=
"acknowledgments"></A>
42 <H2>Acknowledgments
</H2>
44 <P>Gareth Sylvester-Bradley suggested the treatment of large stream offsets used by the Boost Iostreams library and supplied the implementation of
<CODE>offset_to_position
</CODE> and
<CODE>position_to_offset
</CODE> used with the Dinkumware standard library.
</P>
46 <A NAME=
"headers"></A>
49 <DL class=
"page-index">
50 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/positioning.hpp"><CODE><boost/iostreams/positioning.hpp
></CODE></A></DT>
53 <A NAME=
"reference"></A>
56 <A NAME=
"synopsis"></A>
59 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
61 <SPAN CLASS='keyword'
>typedef
</SPAN> <A CLASS='documented' HREF='../../../integer/doc/html/boost_integer/cstdint.html' TARGET='_top'
>boost::intmax_t
</A> stream_offset;
62 std::streampos
<A CLASS='documented' HREF='#offset_to_position'
>offset_to_position
</A>(stream_offset n);
63 stream_offset
<A CLASS='documented' HREF='#position_to_offset'
>position_to_offset
</A>(std::streampos pos);
65 } }
<SPAN CLASS='comment'
>// End namespace boost::io
</SPAN></PRE>
67 <A NAME=
"offset_to_position"></A>
68 <H4>Function template
<CODE>offset_to_position
</CODE></H4>
70 <PRE CLASS=
"broken_ie">std::streampos offset_to_position(stream_offset n);
</PRE>
72 <P>Returns a
<CODE>std::streampos
</CODE> representing the
<CODE>n
</CODE><I>th
</I> position in a stream.
</P>
74 <A NAME=
"position_to_offset"></A>
75 <H4>Function template
<CODE>position_to_offset
</CODE></H4>
77 <PRE CLASS=
"broken_ie">stream_offset position_to_offset(std::streampos pos);
</PRE>
79 <P>Returns a
<CODE>stream_offset
</CODE> representing the same character position as
<CODE>pos
</CODE>, disregarding any code-conversion state.
</P>
85 <P CLASS=
"copyright">© Copyright
2008 <a href=
"http://www.coderage.com/" target=
"_top">CodeRage, LLC
</a><br/>© Copyright
2004-
2007 <a href=
"http://www.coderage.com/turkanis/" target=
"_top">Jonathan Turkanis
</a></P>
87 Distributed under the Boost Software License, Version
1.0. (See accompanying file LICENSE_1_0.txt or copy at
<A HREF=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt
</A>)