Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r74222 - in sandbox/endian: boost/endian libs/endian/doc libs/endian/example libs/endian/test
From: bdawes_at_[hidden]
Date: 2011-09-04 09:51:50


Author: bemandawes
Date: 2011-09-04 09:51:49 EDT (Sun, 04 Sep 2011)
New Revision: 74222
URL: http://svn.boost.org/trac/boost/changeset/74222

Log:
Continue cleanup
Text files modified:
   sandbox/endian/boost/endian/integers.hpp | 2
   sandbox/endian/libs/endian/doc/conversion.html | 33 ++++++++++++++--
   sandbox/endian/libs/endian/doc/index.html | 72 ++++++++++++++++++++++++++++++------
   sandbox/endian/libs/endian/doc/integers.html | 78 +++++++++++----------------------------
   sandbox/endian/libs/endian/example/endian_example.cpp | 5 +-
   sandbox/endian/libs/endian/test/endian_test.cpp | 1
   6 files changed, 113 insertions(+), 78 deletions(-)

Modified: sandbox/endian/boost/endian/integers.hpp
==============================================================================
--- sandbox/endian/boost/endian/integers.hpp (original)
+++ sandbox/endian/boost/endian/integers.hpp 2011-09-04 09:51:49 EDT (Sun, 04 Sep 2011)
@@ -1,4 +1,4 @@
-// boost/endian/types.hpp ------------------------------------------------------------//
+// boost/endian/integers.hpp ---------------------------------------------------------//
 
 // (C) Copyright Darin Adler 2000
 // (C) Copyright Beman Dawes 2006, 2009

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-04 09:51:49 EDT (Sun, 04 Sep 2011)
@@ -25,8 +25,31 @@
   <tr>
     <td>Boost Home&nbsp;&nbsp;&nbsp;&nbsp;
     <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
- Conversion Reference&nbsp;&nbsp;&nbsp;&nbsp;
- Types Reference&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
+ Conversion Functions&nbsp;&nbsp;&nbsp;&nbsp;
+ Integer Types&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
+ </tr>
+</table>
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
+ <tr>
+ <td width="100%" bgcolor="#D7EEFF" align="center">
+ <i><b>Contents</b></i></td>
+ </tr>
+ <tr>
+ <td width="100%" bgcolor="#E8F5FF">
+ Introduction<br>
+ Reference<br>
+&nbsp;&nbsp;&nbsp; Synopsis<br>
+&nbsp;&nbsp;&nbsp; Members<br>
+ Acknowledgements</td>
+ </tr>
+ <tr>
+ <td width="100%" bgcolor="#D7EEFF" align="center">
+ <b><i>Headers</i></b></td>
+ </tr>
+ <tr>
+ <td width="100%" bgcolor="#E8F5FF">
+ <boost/endian/conversion.hpp><br>
+ <boost/endian/integers.hpp></td>
   </tr>
 </table>
 
@@ -34,7 +57,7 @@
 
 <p>Header boost/endian/conversion.hpp
 provides functions that convert built-in
-integers from the native byte ordering to or from big or little endian byte
+integers between native byte ordering and big or little endian byte
 ordering.</p>
 
 <h2><a name="Reference">Reference</a></h2>
@@ -80,7 +103,7 @@
 
 } // namespace endian
 } // namespace boost</pre>
-<h3 dir="ltr">Members</h3>
+<h3 dir="ltr"><a name="Members">Members</a></h3>
 <pre dir="ltr">inline void reorder(int16_t&amp; x);
 inline void reorder(int32_t&amp; x);
 inline void reorder(int64_t&amp; x);
@@ -122,7 +145,7 @@
 support endian conversion as separate from endian types.</p>
 <hr>
 <p>Last revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p>
+<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
 <p>© Copyright Beman Dawes, 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>

Modified: sandbox/endian/libs/endian/doc/index.html
==============================================================================
--- sandbox/endian/libs/endian/doc/index.html (original)
+++ sandbox/endian/libs/endian/doc/index.html 2011-09-04 09:51:49 EDT (Sun, 04 Sep 2011)
@@ -25,10 +25,56 @@
   <tr>
     <td>Boost Home&nbsp;&nbsp;&nbsp;&nbsp;
     <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
- Conversion Reference&nbsp;&nbsp;&nbsp;&nbsp;
- Types Reference&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
+ Conversion Functions&nbsp;&nbsp;&nbsp;&nbsp;
+ Integer Types&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
   </tr>
 </table>
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
+ <tr>
+ <td width="100%" bgcolor="#D7EEFF" align="center">
+ <i><b>Contents</b></i></td>
+ </tr>
+ <tr>
+ <td width="100%" bgcolor="#E8F5FF">
+ Abstract<br>
+ Introduction to endianness<br>
+ Introduction to the Boost.Endian library<br>
+ Acknowledgements</td>
+ </tr>
+ <tr>
+ <td width="100%" bgcolor="#D7EEFF" align="center">
+ <b><i>Headers</i></b></td>
+ </tr>
+ <tr>
+ <td width="100%" bgcolor="#E8F5FF">
+ <boost/endian/conversion.hpp><br>
+ <boost/endian/integers.hpp></td>
+ </tr>
+</table>
+<h2><a name="Abstract">Abstract</a></h2>
+
+<p>Boost.Endian provides facilities to manipulate the byte ordering of integers.</p>
+<ul>
+ <li>The primary use case is binary I/O of integers for portable exchange with
+ other systems, via either file or network transmission.<br>
+&nbsp;</li>
+ <li>A secondary use case is minimizing storage size via integers of sizes
+ and/or alignments not supported by the built-in types. Integers 1, 2, 3, 4, 5,
+ 6, 7, and 8 bytes in length are supported.<br>
+&nbsp;</li>
+ <li>Two distinct approaches to byte ordering are provided. Each approach has a
+ long history of successful use, and each approach has use cases where it is
+ superior to the other approach.<br>
+&nbsp;<ul>
+ <li>The explicit approach provides <a href="conversion.html">conversion
+ functions</a> to reorder bytes. All four combinations of non-modifying or
+ modifying, and unconditional or conditional, functions are provided.<br>
+&nbsp;</li>
+ <li>The implicit approach provides integer types
+ that mimic the built-in integers, implicitly handling all byte reordering.</li>
+ </ul>
+ </li>
+</ul>
 
 <h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
 
@@ -54,23 +100,23 @@
 the least-significant byte first, while SPARC CPU's place the most-significant
 byte first. Some CPU's, such as the PowerPC, allow the operating system to
 choose which ordering applies.</p>
-<p>The most-significant byte first ordering is traditionally called &quot;big endian&quot;
-ordering and the least-significant byte first is traditionally called
+<p><a name="definition"></a>Most-significant-byte-first ordering is traditionally called &quot;big endian&quot;
+ordering and the least-significant-byte-first is traditionally called
 &quot;little-endian&quot; ordering. The names are derived from
 <a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
 Jonathan Swift</a>'s satirical novel <i>
 <a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
-Gulliver’s Travels</a></i>, where rival kingdom's opened their soft-boiled eggs
+Gulliver’s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
 at different ends.</p>
-<p>For a more complete introduction to endianness, see the Wikipedia's
-Endianness article.</p>
+<p>See the Wikipedia's
+Endianness article for an
+extensive discussion of endianness.</p>
 <p>Except for reading an occasional core dump, most programmers can ignore
-endianness. But when exchanging data with other computer systems, whether by
-file transfers or over a network, programmers have to deal with endianness when
-binary data is involved.</p>
-<h2><a name="Introduction">Introduction</a> to the Boost Endian Library</h2>
+endianness. But when exchanging binary integers with other computer systems, whether by
+file transfers or over a network, programmers have to deal with endianness. </p>
+<h2><a name="Introduction">Introduction</a> to the Boost.Endian library</h2>
 
-<p>The Boost Endian Library provides facilities to deal with integer endianness.</p>
+<p>The Boost.Endian library provides facilities to deal with integer endianness.</p>
 
 <p>The library provides two approaches to dealing with integer endianness:</p>
 
@@ -115,7 +161,7 @@
 Yuval Ronen.</p>
 <hr>
 <p>Last revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p>
+<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
 <p>© Copyright Beman Dawes, 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>

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-04 09:51:49 EDT (Sun, 04 Sep 2011)
@@ -18,7 +18,7 @@
 <a href="../../../index.html">
 <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
     <td width="413" align="middle">
- <font size="7">Endian Integers</font>
+ <font size="7">Endian Integer Types</font>
     </td>
   </tr>
 </table>
@@ -27,8 +27,8 @@
   <tr>
     <td>Boost Home&nbsp;&nbsp;&nbsp;&nbsp;
     <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
- Conversion Reference&nbsp;&nbsp;&nbsp;&nbsp;
- Types Reference&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
+ Conversion Functions&nbsp;&nbsp;&nbsp;&nbsp;
+ Integer Types&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
   </tr>
 </table>
 
@@ -50,7 +50,6 @@
       <a href="#Synopsis">Synopsis</a><br>
       &nbsp;&nbsp;&nbsp; Members<br>
       <a href="#FAQ">FAQ</a><br>
- Binary I/O warnings and cautions<br>
       <a href="#Example">Example</a><br>
       <a href="#Design">Design</a><br>
       <a href="#Experience">Experience</a><br>
@@ -66,14 +65,12 @@
   </tr>
   <tr>
     <td width="100%" bgcolor="#E8F5FF">
- <boost/integer/endian.hpp><br>
- <boost/integer/endian_binary_stream.hpp><br>
- <boost/binary_stream.hpp></td>
+ <boost/endian/conversion.hpp><br>
+ <boost/endian/integers.hpp></td>
   </tr>
 </table>
 <h2><a name="Introduction">Introduction</a></h2>
-<p>Header
- <boost/integer/endian.hpp> provides
+<p>Header <boost/endian/integers.hpp> provides
 integer-like byte-holder binary types with explicit control over
 byte order, value type, size, and alignment. Typedefs provide easy-to-use names
 for common configurations.</p>
@@ -100,13 +97,6 @@
 <code>&gt;&gt;=</code>. Binary relational operators are <code>==</code>, <code>!=</code>,
 <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code>.</p>
 <p>Automatic conversion is provided to the underlying integer value type.</p>
-<p>Header <boost/integer/endian_binary_stream.hpp>
-provides operators &lt;= and <code>=&gt;</code> for unformatted binary (as opposed to
-formatted character) stream insertion and extraction of endian types.</p>
-<p>Header <boost/binary_stream.hpp>
-provides operators &lt;= and <code>=&gt;</code> for unformatted binary (as opposed to
-formatted character) stream insertion and extraction of built-in and std::string
-types.</p>
 <h2><a name="Hello-endian-world">Hello endian world</a></h2>
 <blockquote>
   <pre>#include &lt;boost/integer/endian.hpp&gt;
@@ -268,7 +258,7 @@
 rather than <code>big56_t</code>.</p>
 <p>As experience using these type grows, the realization creeps in that they are
 lousy arithmetic integers - they are really byte holders that for convenience
-support arithmetic operations - and that for use in internal interfaces or
+support arithmetic operations - and for use in internal interfaces or
 anything more than trivial arithmetic computations it is far better to convert
 values of these endian types to traditional integer types.</p>
 <p>That seems to lead to formation of a new mental model specific to endian byte-holder types. In that model, the endianness
@@ -282,7 +272,7 @@
 <h3><a name="Synopsis">Synopsis</a></h3>
 <pre>namespace boost
 {
- namespace integer
+ namespace endian
   {
      
     enum class <a name="endianness">endianness</a> { big, little, native }; // scoped enum emulated on C++03
@@ -290,7 +280,7 @@
 
     template &lt;endianness E, typename T, std::size_t n_bits,
       alignment A = alignment::unaligned&gt;
- class endian : integer_cover_operators&lt; endian&lt;E, T, n_bits, A&gt;, T &gt;
+ class endian : cover_operators&lt; endian&lt;E, T, n_bits, A&gt;, T &gt;
     {
     public:
       typedef T value_type;
@@ -300,7 +290,7 @@
       <a href="#endian">endian</a>() = default; // = default replaced by {} on C++03
       explicit endian(T v);
 
- endian &amp; operator=(T v);
+ endian&amp; operator=(T v);
       <a href="#operator-T">operator T</a>() const;
       const char* data() const;
     };
@@ -391,7 +381,7 @@
     // aligned native endian typedefs are not provided because
     // &lt;cstdint&gt; types are superior for this use case
 
- } // namespace integer
+ } // namespace endian
 } // namespace boost</pre>
 <h3><a name="Members">Members</a></h3>
 <p><code><a name="endian">endian</a>() = default;&nbsp; // C++03: endian(){}</code></p>
@@ -404,7 +394,7 @@
 <p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
 constructed object.</p>
 </blockquote>
-<p><code>endian &amp; <a name="operator-eq">operator=</a>(T v);</code></p>
+<p><code>endian&amp; <a name="operator-eq">operator=</a>(T v);</code></p>
 <blockquote>
   <p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
   constructed object.</p>
@@ -429,7 +419,7 @@
 of additional binary integer sizes and alignments is important in some
 applications.</p>
 <p><b>Why not just use Boost.Serialization?</b> Serialization involves a
-conversion for every object involved in I/O. Endian objects require no
+conversion for every object involved in I/O. Endian integers require no
 conversion or copying. They are already in the desired format for binary I/O.
 Thus they can be read or written in bulk.</p>
 <p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
@@ -441,16 +431,15 @@
 text utilities on the resulting files, limit usefulness to applications where
 the
 binary I/O advantages are paramount.</p>
-<p><b>Do these types have any uses outside of I/O?</b> Probably not, except for
-native endianness which can be used for fine grained control over size and
-alignment.</p>
+<p><b>Do these types have any uses outside of I/O?</b> Native endianness can be used for fine grained control over size and
+alignment, so may be used to save memory in applications not related to I/O.</p>
 <p><b>Is there is a performance hit when doing arithmetic using these types?</b> Yes, for sure,
 compared to arithmetic operations on native integer types. However, these types
 are usually be faster, and sometimes much faster, for I/O compared to stream
 inserters and extractors, or to serialization.</p>
 <p><b>Are endian types POD's?</b> Yes for C++0x. No for C++03, although several
 <a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
-<p><b>What are the implications endian types not being POD's with C++03
+<p><b>What are the implications endian integer types not being POD's with C++03
 compilers?</b> They
 can't be used in unions. Also, compilers aren't required to align or lay
 out storage in portable ways, although this potential problem hasn't prevented
@@ -478,40 +467,19 @@
 incrementing a variable in a record. It is very convenient to write:</p>
 <pre wrap> ++record.foo;</pre>
 <p wrap>Rather than:</p>
-<pre wrap> int temp( record.foo);
+<pre wrap> int temp(record.foo);
     ++temp;
     record.foo = temp;</pre>
-<p wrap><b>Why do binary stream insertion and extraction use operators &lt;= and &gt;=
-rather than &lt;&lt;= and &gt;&gt;=?</b> &lt;&lt;= and &gt;&gt;= associate right-to-left, which is the
-opposite of &lt;&lt; and &gt;&gt;, so would be very confusing and error prone. &lt;= and &gt;=
-associate left-to-right. </p>
-<h2><a name="Binary-I-O-cautions">Binary I/O warnings and cautions</a></h2>
-<p><font color="#FF0000"><b><i><span style="background-color: #FFFFFF">Warning:</span></i></b></font><span style="background-color: #FFFFFF"> </span>&nbsp;Use
-only on streams opened with filemode <code>std::ios_base::binary</code>. Thus
-unformatted binary I/O should not be with the standard streams (cout, cin, etc.)
-since they are opened in text mode. Use on text streams may produce incorrect
-results, such as insertion of unwanted characters or premature end-of-file. For
-example, on Windows 0x0D would become 0x0D, 0x0A.</p>
-<p><i><b><font color="#FF0000">Caution:</font><font color="#FFFF00"> </font></b>
-</i>When mixing formatted (i.e. operator &lt;&lt; or &gt;&gt;) and unformatted (i.e.
-operator &lt;= or &gt;=) stream I/O, be aware that &lt;&lt; and &gt;&gt; take precedence over &lt;=
-and &gt;=. Use parentheses to force correct order of evaluation. For example:</p>
-<blockquote>
- <pre>my_stream &lt;&lt; foo &lt;= bar; // no parentheses needed
-(my_stream &lt;= foo) &lt;&lt; bar; // parentheses required </pre>
-</blockquote>
-<p>As a practical matter, it may be easier and safer to never mix the character
-and binary insertion or extraction operators in the same statement.</p>
 <h2><a name="Example">Example</a></h2>
 <p>The endian_example.cpp program writes a
 binary file containing four byte big-endian and little-endian integers:</p>
 <blockquote>
   <pre>#include &lt;iostream&gt;
-#include &lt;cassert&gt;
 #include &lt;cstdio&gt;
-#include &lt;boost/integer/endian.hpp&gt;
+#include &lt;boost/endian/integers.hpp&gt;
+#include &lt;boost/static_assert.hpp&gt;
 
-using namespace boost::integer;
+using namespace boost::endian;
 
 namespace
 {
@@ -533,7 +501,7 @@
 
 int main()
 {
- assert( sizeof( header ) == 16 ); // requirement for interoperability
+ BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
 
   header h;
 
@@ -572,7 +540,7 @@
 <blockquote>
   <pre>0403 0201 0000 0010 ffff ffff 0102 0304</pre>
 </blockquote>
-<h2><a name="Design">Design</a> considerations for Boost.Endian</h2>
+<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>
   <li>Must provide exactly the size and internal byte ordering specified.</li>
@@ -639,7 +607,7 @@
 differs from endian representation size.</p>
 <hr>
 <p>Last revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p>
+<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
 <p>© Copyright Beman Dawes, 2006-2009</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>

Modified: sandbox/endian/libs/endian/example/endian_example.cpp
==============================================================================
--- sandbox/endian/libs/endian/example/endian_example.cpp (original)
+++ sandbox/endian/libs/endian/example/endian_example.cpp 2011-09-04 09:51:49 EDT (Sun, 04 Sep 2011)
@@ -16,7 +16,6 @@
 #include <iostream>
 #include <cstdio>
 #include <boost/endian/integers.hpp>
-#include <boost/detail/lightweight_main.hpp>
 #include <boost/static_assert.hpp>
 
 using namespace boost::endian;
@@ -39,9 +38,9 @@
   const char * filename = "test.dat";
 }
 
-int cpp_main(int, char * [])
+int main(int, char * [])
 {
- BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // requirement for interoperability
+ BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
   
   header h;
 

Modified: sandbox/endian/libs/endian/test/endian_test.cpp
==============================================================================
--- sandbox/endian/libs/endian/test/endian_test.cpp (original)
+++ sandbox/endian/libs/endian/test/endian_test.cpp 2011-09-04 09:51:49 EDT (Sun, 04 Sep 2011)
@@ -20,7 +20,6 @@
 
 #include <boost/endian/integers.hpp>
 #include <boost/cstdint.hpp>
-#include <boost/progress.hpp>
 #include <boost/detail/lightweight_main.hpp>
 
 #include <iostream>


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