Boost-Commit :

Date view	Thread view	Subject view	Author view

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    
     <a href="index.html">Endian Home</a>    
- Conversion Reference    
- Types Reference     Tutorial</td>
+ Conversion Functions    
+ Integer Types     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>
+    Synopsis<br>
+    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& x);
inline void reorder(int32_t& x);
inline void reorder(int64_t& x);
@@ -122,7 +145,7 @@
support endian conversion as separate from endian types.</p>
<hr>
<p>Last revised:
-03 September, 2011</p>
+04 September, 2011</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    
     <a href="index.html">Endian Home</a>    
- Conversion Reference    
- Types Reference     Tutorial</td>
+ Conversion Functions    
+ Integer Types     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>
+ </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>
+ </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>
+ <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>
+ </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 "big endian"
-ordering and the least-significant byte first is traditionally called
+<p><a name="definition"></a>Most-significant-byte-first ordering is traditionally called "big endian"
+ordering and the least-significant-byte-first is traditionally called
"little-endian" 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:
-03 September, 2011</p>
+04 September, 2011</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    
     <a href="index.html">Endian Home</a>    
- Conversion Reference    
- Types Reference     Tutorial</td>
+ Conversion Functions    
+ Integer Types     Tutorial</td>
   </tr>
</table>

@@ -50,7 +50,6 @@
       <a href="#Synopsis">Synopsis</a><br>
           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>>>=</code>. Binary relational operators are <code>==</code>, <code>!=</code>,
<code><</code>, <code><=</code>, <code>></code>, <code>>=</code>.</p>
<p>Automatic conversion is provided to the underlying integer value type.</p>
-<p>Header <boost/integer/endian_binary_stream.hpp>
-provides operators <= and <code>=></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 <= and <code>=></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 <boost/integer/endian.hpp>
@@ -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 <endianness E, typename T, std::size_t n_bits,
       alignment A = alignment::unaligned>
- class endian : integer_cover_operators< endian<E, T, n_bits, A>, T >
+ class endian : cover_operators< endian<E, T, n_bits, A>, T >
     {
     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 & operator=(T v);
+ endian& 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
     // <cstdint> 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;  // 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 & <a name="operator-eq">operator=</a>(T v);</code></p>
+<p><code>endian& <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 <= and >=
-rather than <<= and >>=?</b> <<= and >>= associate right-to-left, which is the
-opposite of << and >>, so would be very confusing and error prone. <= and >=
-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> 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 << or >>) and unformatted (i.e.
-operator <= or >=) stream I/O, be aware that << and >> take precedence over <=
-and >=. Use parentheses to force correct order of evaluation. For example:</p>
-<blockquote>
- <pre>my_stream << foo <= bar; // no parentheses needed
-(my_stream <= foo) << 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 <iostream>
-#include <cassert>
#include <cstdio>
-#include <boost/integer/endian.hpp>
+#include <boost/endian/integers.hpp>
+#include <boost/static_assert.hpp>

-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:
-03 September, 2011</p>
+04 September, 2011</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>

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