Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r74247 - sandbox/endian/libs/endian/doc
From: bdawes_at_[hidden]
Date: 2011-09-05 20:11:28

Author: bemandawes
Date: 2011-09-05 20:11:27 EDT (Mon, 05 Sep 2011)
New Revision: 74247
URL: http://svn.boost.org/trac/boost/changeset/74247

Log:
Fix integers.html doc mistake, and clarify conversion.html, as reported by Gordon Woodhull.
Text files modified:
   sandbox/endian/libs/endian/doc/conversion.html | 24 ++++-
   sandbox/endian/libs/endian/doc/integers.html | 154 ++++++++++++++++-----------------------
   2 files changed, 81 insertions(+), 97 deletions(-)

Modified: sandbox/endian/libs/endian/doc/conversion.html
==============================================================================
--- sandbox/endian/libs/endian/doc/conversion.html (original)
+++ sandbox/endian/libs/endian/doc/conversion.html 2011-09-05 20:11:27 EDT (Mon, 05 Sep 2011)
@@ -128,24 +128,38 @@
template <class T> void big_to_native(T& x);
template <class T> void little_to_native(T& x);</pre>
<blockquote>
- Effects: If the native byte ordering and indicated byte
- ordering are different, <code>reorder(x)</code>, otherwise no effect.
+ Effects: If the native byte ordering and byte
+ ordering indicated by the function name are different, <code>reorder(x)</code>, otherwise no effect.
+ Example:
+ <blockquote>
+ <pre>int32_t x = some-value;
+native_to_big(x); // converts x to big-endian unless
+ // the native representation is already big-endian</pre>
+ </blockquote>
</blockquote>
<pre dir="ltr">template <class T> void native_to_big(T source, T& target);
template <class T> void native_to_little(T source, T& target);
template <class T> void big_to_native(T source, T& target);
template <class T> void little_to_native(T source, T& target);</pre>
<blockquote>
- Effects: If the native byte ordering and indicated byte
- ordering are different, <code>reorder(source, target)</code>, otherwise <code>
+ Effects: If the native byte ordering and byte
+ ordering indicated by the function name are different, <code>reorder(source, target)</code>, otherwise <code>
target = source</code>.
+ Example:
+ <blockquote>
+ <pre>int32_t x;
+... read an external little-endian value into x ...
+int32_t y;
+little_to_native(x, y); // if native ordering is big-endian, reorder(x, y),
+ // otherwise y = x</pre>
+ </blockquote>
</blockquote>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
Tomas Puverle was instrumental in identifying and articulating the need to
support endian conversion as separate from endian types.
<hr>
Last revised:
-04 September, 2011
+05 September, 2011
© Copyright Beman Dawes, 2011
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>

Modified: sandbox/endian/libs/endian/doc/integers.html
==============================================================================
--- sandbox/endian/libs/endian/doc/integers.html (original)
+++ sandbox/endian/libs/endian/doc/integers.html 2011-09-05 20:11:27 EDT (Mon, 05 Sep 2011)
@@ -40,7 +40,7 @@
 <tr>
 <td width="100%" bgcolor="#E8F5FF">
 <a href="#Introduction">Introduction</a> 
- Hello endian world 
+ Example 
 <a href="#Limitations">Limitations</a> 
 <a href="#Feature-set">Feature set</a> 
 <a href="#Types">Typedefs</a> 
@@ -50,7 +50,6 @@
 <a href="#Synopsis">Synopsis</a> 
     Members 
 <a href="#FAQ">FAQ</a> 
- Example 
 <a href="#Design">Design</a> 
 <a href="#Experience">Experience</a> 
 <a href="#Motivating-use-cases">Motivating use cases</a> 
@@ -97,35 +96,76 @@
<code>>>=</code>. Binary relational operators are <code>==</code>, <code>!=</code>,
<code><</code>, <code><=</code>, <code>></code>, <code>>=</code>.
Automatic conversion is provided to the underlying integer value type.
-<h2><a name="Hello-endian-world">Hello endian world</a></h2>
+<h2><a name="Example">Example</a></h2>
+The endian_example.cpp program writes a
+binary file containing four byte big-endian and little-endian integers:
<blockquote>
- <pre>#include <boost/integer/endian.hpp>
-#include <boost/integer/endian_binary_stream.hpp>
-#include <boost/binary_stream.hpp>
-#include <iostream>
+ <pre>#include <iostream>
+#include <cstdio>
+#include <boost/endian/integers.hpp>
+#include <boost/static_assert.hpp>

-using namespace boost;
-using namespace boost::integer;
+using namespace boost::endian;
+
+namespace
+{
+ // This is an extract from a very widely used GIS file format. I have no idea
+ // why a designer would mix big and little endians in the same file - but
+ // this is a real-world format and users wishing to write low level code
+ // manipulating these files have to deal with the mixed endianness.
+
+ struct header
+ {
+ big32_t file_code;
+ big32_t file_length;
+ little32_t version;
+ little32_t shape_type;
+ };
+
+ const char * filename = "test.dat";
+}

int main()
{
- int_least32_t v = 0x31323334L; // = ASCII { '1', '2', '3', '4' }
- // value chosen to work on text stream
- big32_t b(v);
- little32_t l(v);
+ BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
+
+ header h;

- std::cout << "Hello, endian world!\n\n";
+ h.file_code = 0x01020304;
+ h.file_length = sizeof( header );
+ h.version = -1;
+ h.shape_type = 0x01020304;
+
+ // Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes
+ // used for binary file operations when ultimate efficiency is important.
+ // Such I/O is often performed in some C++ wrapper class, but to drive home the
+ // point that endian integers are often used in fairly low-level code that
+ // does bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example.
+
+ std::FILE * fi;
+
+ if ( !(fi = std::fopen( filename, "wb" )) ) // MUST BE BINARY
+ {
+ std::cout << "could not open " << filename << '\n';
+ return 1;
+ }

- std::cout << v << ' ' << b << ' ' << l << '\n';
- std::cout <= v <= ' ' <= b <= ' ' <= l <= '\n';
+ if ( std::fwrite( &h, sizeof( header ), 1, fi ) != 1 )
+ {
+ std::cout << "write failure for " << filename << '\n';
+ return 1;
+ }
+
+ std::fclose( fi );
+
+ std::cout << "created file " << filename << '\n';
+ return 0;
}</pre>
</blockquote>
-On a little-endian CPU, this program outputs:
+After compiling and executing endian_example.cpp,
+a hex dump of <code>test.dat</code> shows:
<blockquote>
- <pre>Hello, endian world!
-
-825373492 825373492 825373492
-4321 1234 4321</pre>
+ <pre>0102 0304 0000 0010 ffff ffff 0403 0201</pre>
</blockquote>
<h2><a name="Limitations">Limitations</a></h2>
Requires <code><climits></code> <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code>
@@ -470,76 +510,6 @@
<pre wrap> int temp(record.foo);
 ++temp;
 record.foo = temp;</pre>
-<h2><a name="Example">Example</a></h2>
-The endian_example.cpp program writes a
-binary file containing four byte big-endian and little-endian integers:
-<blockquote>
- <pre>#include <iostream>
-#include <cstdio>
-#include <boost/endian/integers.hpp>
-#include <boost/static_assert.hpp>
-
-using namespace boost::endian;
-
-namespace
-{
- // This is an extract from a very widely used GIS file format. I have no idea
- // why a designer would mix big and little endians in the same file - but
- // this is a real-world format and users wishing to write low level code
- // manipulating these files have to deal with the mixed endianness.
-
- struct header
- {
- big32_t file_code;
- big32_t file_length;
- little32_t version;
- little32_t shape_type;
- };
-
- const char * filename = "test.dat";
-}
-
-int main()
-{
- BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
-
- header h;
-
- h.file_code = 0x04030201;
- h.file_length = sizeof( header );
- h.version = -1;
- h.shape_type = 0x04030201;
-
- // Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes
- // used for binary file operations when ultimate efficiency is important.
- // Such I/O is often performed in some C++ wrapper class, but to drive home the
- // point that endian integers are often used in fairly low-level code that
- // does bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example.
-
- std::FILE * fi;
-
- if ( !(fi = std::fopen( filename, "wb" )) ) // MUST BE BINARY
- {
- std::cout << "could not open " << filename << '\n';
- return 1;
- }
-
- if ( std::fwrite( &h, sizeof( header ), 1, fi ) != 1 )
- {
- std::cout << "write failure for " << filename << '\n';
- return 1;
- }
-
- std::fclose( fi );
-
- std::cout << "created file " << filename << '\n';
- return 0;
-}</pre>
-</blockquote>
-After compiling and executing endian_example.cpp, a hex dump of <code>test.dat</code> shows:
-<blockquote>
- <pre>0403 0201 0000 0010 ffff ffff 0102 0304</pre>
-</blockquote>
<h2><a name="Design">Design</a> considerations for Boost.Endian integers</h2>
<ul>
 <li>Must be suitable for I/O - in other words, must be memcpyable.</li>
@@ -607,7 +577,7 @@
differs from endian representation size.
<hr>
Last revised:
-04 September, 2011
+05 September, 2011
© Copyright Beman Dawes, 2006-2009
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>

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk