forked from boostorg/endian
bemandawes
c3d5f2e2f8
git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@71463 b8fc166d-592f-0410-95f2-cb63ce0dd405
103 lines
3.8 KiB
HTML
103 lines
3.8 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|
<title>Binary Stream I/O</title>
|
|
<link rel="stylesheet" type="text/css" href="../../../doc/html/minimal.css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1>Proposal for Binary Stream I/O</h1>
|
|
<h2>Introduction</h2>
|
|
<p>The C++ standard library's stream I/O facilities are type-safe and very
|
|
convenient for performing formatted (i.e. human readable) I/O. But they offer only
|
|
rudimentary and not very type-safe operations for performing unformatted binary I/O.
|
|
Although formatted I/O is often preferable, some applications need the speed and
|
|
storage efficiency of unformatted binary I/O or need to interoperate with third-party
|
|
applications that require unformatted binary file or network data formats.</p>
|
|
<p>Standard library streams can be opened with filemode <code>
|
|
std::ios_base::binary</code>, so binary I/O is possible. But the only
|
|
unformatted I/O functions available are <code>get()</code>, <code>put()</code>,
|
|
<code>read()</code>, and <code>write()</code>. These operate only on <code>char</code>
|
|
or array of <code>char</code> (with length explicitly specified), so require the
|
|
user to write casts, are hard to use, and are error prone.</p>
|
|
<p>There have been many requests on Boost and various C++ newsgroups for
|
|
unformatted binary I/O. For example, in 2003 Neal Becker wrote:</p>
|
|
<blockquote>
|
|
<p>I wonder if anyone has code for implementing unformatted I/O? What I
|
|
have in mind is for the simple case where the application that reads data knows
|
|
the data types, so this is not as complicated as the general marshalling
|
|
situation.</p>
|
|
</blockquote>
|
|
<p>This proposal provides a simple solution that works with standard library
|
|
input and output streams. The one caveat is that the stream must be opened with filemode <code>std::ios_base::binary</code>
|
|
to avoid certain data values being treated as line endings.</p>
|
|
<h2>Synopsis</h2>
|
|
<div dir="ltr">
|
|
<pre>namespace boost
|
|
{
|
|
template <class T>
|
|
<i>unspecified-type-1<T></i> bin(const T& x);
|
|
|
|
template <class T>
|
|
<i>unspecified-type-2<T></i> bin(T& x);
|
|
|
|
template <class T>
|
|
std::ostream& operator<<(std::ostream& os, <i>unspecified-type-1<T></i> x);
|
|
|
|
template <class T>
|
|
std::ostream& operator<<(std::ostream& os, <i>unspecified-type-2<T></i> x);
|
|
|
|
template <class T>
|
|
std::istream& operator>>(std::istream& is, <i>unspecified-type-2<T></i> x);
|
|
}</pre>
|
|
</div>
|
|
<p><i><code>unspecified-type-1</code></i> and <i><code>unspecified-type-2</code></i>
|
|
are implementation supplied types.</p>
|
|
<h2>Example</h2>
|
|
<blockquote>
|
|
<pre>int main()
|
|
{
|
|
fstream f("binary_stream_example.dat",
|
|
std::ios_base::trunc | std::ios_base::in | std::ios_base::out | std::ios_base::binary);
|
|
|
|
int32_t x = 0x01020304;
|
|
int32_t y = 0;
|
|
|
|
f << bin(x);
|
|
f.seekg(0);
|
|
f >> bin(y);
|
|
|
|
BOOST_ASSERT(x == y);
|
|
|
|
return 0;
|
|
}</pre>
|
|
</blockquote>
|
|
<p>The file produced with be four bytes in length. On a big-endian machine, the
|
|
contents in hexadecimal are:</p>
|
|
<blockquote>
|
|
<pre>01020304</pre>
|
|
</blockquote>
|
|
<p>On a little-endian machine, the contents in hexadecimal are:</p>
|
|
<blockquote>
|
|
<pre>04030201</pre>
|
|
</blockquote>
|
|
<hr>
|
|
<p>Last revised:
|
|
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->24 April, 2011<!--webbot bot="Timestamp" endspan i-checksum="29830" --></p>
|
|
<p>© Copyright Beman Dawes, 2009, 2011</p>
|
|
<p>Distributed under the Boost Software License, Version 1.0. See
|
|
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>
|
|
|
|
<p> </p>
|
|
<p> </p>
|
|
<p> </p>
|
|
<p> </p>
|
|
|
|
</body>
|
|
|
|
</html> |