From 95ccedc67b7a552784a2b4dd39ece6a6c5c55f64 Mon Sep 17 00:00:00 2001 From: bemandawes Date: Sun, 4 Sep 2011 13:51:49 +0000 Subject: [PATCH] Continue cleanup git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@74222 b8fc166d-592f-0410-95f2-cb63ce0dd405 --- boost/endian/integers.hpp | 2 +- libs/endian/doc/conversion.html | 33 +++++++++-- libs/endian/doc/index.html | 72 +++++++++++++++++++----- libs/endian/doc/integers.html | 78 ++++++++------------------ libs/endian/example/endian_example.cpp | 5 +- libs/endian/test/endian_test.cpp | 1 - 6 files changed, 113 insertions(+), 78 deletions(-) diff --git a/boost/endian/integers.hpp b/boost/endian/integers.hpp index 8876025..b4926b5 100644 --- a/boost/endian/integers.hpp +++ b/boost/endian/integers.hpp @@ -1,4 +1,4 @@ -// boost/endian/types.hpp ------------------------------------------------------------// +// boost/endian/integers.hpp ---------------------------------------------------------// // (C) Copyright Darin Adler 2000 // (C) Copyright Beman Dawes 2006, 2009 diff --git a/libs/endian/doc/conversion.html b/libs/endian/doc/conversion.html index 9cf54b3..974a5d0 100644 --- a/libs/endian/doc/conversion.html +++ b/libs/endian/doc/conversion.html @@ -25,8 +25,31 @@ Boost Home     Endian Home     - Conversion Reference     - Types Reference     Tutorial + Conversion Functions     + Integer Types     Tutorial + + + + + + + + + + + + + +
+ Contents
+ Introduction
+ Reference
+    Synopsis
+    Members
+ Acknowledgements
+ Headers
+ <boost/endian/conversion.hpp>
+ <boost/endian/integers.hpp>
@@ -34,7 +57,7 @@

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.

Reference

@@ -80,7 +103,7 @@ namespace endian } // namespace endian } // namespace boost -

Members

+

Members

inline void reorder(int16_t& x);
 inline void reorder(int32_t& x);
 inline void reorder(int64_t& x);
@@ -122,7 +145,7 @@ template <class T> void little_to_native(T source, T& target);
support endian conversion as separate from endian types.

Last revised: -03 September, 2011

+04 September, 2011

© Copyright Beman Dawes, 2011

Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt

diff --git a/libs/endian/doc/index.html b/libs/endian/doc/index.html index c69f26e..f0222a4 100644 --- a/libs/endian/doc/index.html +++ b/libs/endian/doc/index.html @@ -25,10 +25,56 @@ Boost Home     Endian Home     - Conversion Reference     - Types Reference     Tutorial + Conversion Functions     + Integer Types     Tutorial + + + + + + + + + + + + + +
+ Contents
+ Abstract
+ Introduction to endianness
+ Introduction to the Boost.Endian library
+ Acknowledgements
+ Headers
+ <boost/endian/conversion.hpp>
+ <boost/endian/integers.hpp>
+

Abstract

+ +

Boost.Endian provides facilities to manipulate the byte ordering of integers.

+

Introduction to endianness

@@ -54,23 +100,23 @@ output file produces:

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.

-

The most-significant byte first ordering is traditionally called "big endian" -ordering and the least-significant byte first is traditionally called +

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 Jonathan Swift's satirical novel -Gulliver’s Travels, where rival kingdom's opened their soft-boiled eggs +Gulliver’s Travels, where rival kingdoms opened their soft-boiled eggs at different ends.

-

For a more complete introduction to endianness, see the Wikipedia's -Endianness article.

+

See the Wikipedia's +Endianness article for an +extensive discussion of endianness.

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.

-

Introduction to the Boost Endian Library

+endianness. But when exchanging binary integers with other computer systems, whether by +file transfers or over a network, programmers have to deal with endianness.

+

Introduction to the Boost.Endian library

-

The Boost Endian Library provides facilities to deal with integer endianness.

+

The Boost.Endian library provides facilities to deal with integer endianness.

The library provides two approaches to dealing with integer endianness:

@@ -115,7 +161,7 @@ Tomas Puverle, Vincente Botet, and Yuval Ronen.

Last revised: -03 September, 2011

+04 September, 2011

© Copyright Beman Dawes, 2011

Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt

diff --git a/libs/endian/doc/integers.html b/libs/endian/doc/integers.html index 444e68a..cc1d10c 100644 --- a/libs/endian/doc/integers.html +++ b/libs/endian/doc/integers.html @@ -18,7 +18,7 @@ boost.png (6897 bytes) - Endian Integers + Endian Integer Types @@ -27,8 +27,8 @@ Boost Home     Endian Home     - Conversion Reference     - Types Reference     Tutorial + Conversion Functions     + Integer Types     Tutorial @@ -50,7 +50,6 @@ Synopsis
    Members
FAQ
- Binary I/O warnings and cautions
Example
Design
Experience
@@ -66,14 +65,12 @@ - <boost/integer/endian.hpp>
- <boost/integer/endian_binary_stream.hpp>
- <boost/binary_stream.hpp> + <boost/endian/conversion.hpp>
+ <boost/endian/integers.hpp>

Introduction

-

Header - <boost/integer/endian.hpp> provides +

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.

@@ -100,13 +97,6 @@ arithmetic operators are +, +=, -, >>=. Binary relational operators are ==, !=, <, <=, >, >=.

Automatic conversion is provided to the underlying integer value type.

-

Header <boost/integer/endian_binary_stream.hpp> -provides operators <= and => for unformatted binary (as opposed to -formatted character) stream insertion and extraction of endian types.

-

Header <boost/binary_stream.hpp> -provides operators <= and => for unformatted binary (as opposed to -formatted character) stream insertion and extraction of built-in and std::string -types.

Hello endian world

#include <boost/integer/endian.hpp>
@@ -268,7 +258,7 @@ expect a 56-bit big-endian signed integer to be named int_big56_t
 rather than big56_t.

 
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.

 
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 @@ usual operations on integers are supplied.

 
Synopsis

 
namespace boost
 {
-  namespace integer
+  namespace endian
   {
      
     enum class endianness { big, little, native };  // scoped enum emulated on C++03
@@ -290,7 +280,7 @@ usual operations on integers are supplied.

 
     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 @@ usual operations on integers are supplied.

       endian() = default;       // = default replaced by {} on C++03
       explicit endian(T v);
 
-      endian & operator=(T v);
+      endian& operator=(T v);
       operator T() const;
       const char* data() const;
     };
@@ -391,7 +381,7 @@ usual operations on integers are supplied.

     // aligned native endian typedefs are not provided because
     // <cstdint> types are superior for this use case
 
-  } // namespace integer
+  } // namespace endian
 } // namespace boost

 
Members

 
endian() = default;  // C++03: endian(){}

@@ -404,7 +394,7 @@ usual operations on integers are supplied.

 
Postcondition: x == v, where x is the 
 constructed object.
-

endian & operator=(T v);

+

endian& operator=(T v);

Postcondition: x == v, where x is the constructed object.

@@ -429,7 +419,7 @@ and space efficiency. Availability of additional binary integer sizes and alignments is important in some applications.

Why not just use Boost.Serialization? 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.

Why bother with binary I/O? Why not just use C++ Standard Library stream @@ -441,16 +431,15 @@ are possible, easing sorting and allowing direct access. Disadvantages, such as text utilities on the resulting files, limit usefulness to applications where the binary I/O advantages are paramount.

-

Do these types have any uses outside of I/O? Probably not, except for -native endianness which can be used for fine grained control over size and -alignment.

+

Do these types have any uses outside of I/O? 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.

Is there is a performance hit when doing arithmetic using these types? 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.

Are endian types POD's? Yes for C++0x. No for C++03, although several macros are available to force PODness in all cases.

-

What are the implications endian types not being POD's with C++03 +

What are the implications endian integer types not being POD's with C++03 compilers? 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 @@ clutter and makes code both easier to write and to read. Consider incrementing a variable in a record. It is very convenient to write:

    ++record.foo;

Rather than:

-
    int temp( record.foo);
+
    int temp(record.foo);
     ++temp;
     record.foo = temp;

-
Why do binary stream insertion and extraction use operators <= and >= 
-rather than <<= and >>=? <<= and >>= associate right-to-left, which is the 
-opposite of << and >>, so would be very confusing and error prone. <= and >= 
-associate left-to-right. 

-
Binary I/O warnings and cautions

-
Warning:  Use 
-only on streams opened with filemode std::ios_base::binary. 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.

-
Caution: 
-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:

-

-  
my_stream << foo <= bar;    // no parentheses needed
-(my_stream <= foo) << bar;  // parentheses required 

-

-
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.

 
Example

 
The endian_example.cpp program writes a 
 binary file containing four byte big-endian and little-endian integers:

 

   
#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 @@ namespace
 
 int main()
 {
-  assert( sizeof( header ) == 16 );  // requirement for interoperability
+  BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
 
   header h;
 
@@ -572,7 +540,7 @@ int main()
 

   
0403 0201 0000 0010 ffff ffff 0102 0304

 

-
Design considerations for Boost.Endian

+
Design considerations for Boost.Endian integers

 
    
   
  • Must be suitable for I/O - in other words, must be memcpyable.
    • 
   
  • Must provide exactly the size and internal byte ordering specified.
    • 
@@ -639,7 +607,7 @@ sign partial specialization to correctly extend the sign when cover integer size
 differs from endian representation size.
    
 
    
 
    Last revised:
-03 September, 2011
    
+04 September, 2011
    
 
    © Copyright Beman Dawes, 2006-2009
    
 
    Distributed under the Boost Software License, Version 1.0. See
 www.boost.org/ LICENSE_1_0.txt
    
diff --git a/libs/endian/example/endian_example.cpp b/libs/endian/example/endian_example.cpp
index 8b7159f..48b1b0b 100644
--- a/libs/endian/example/endian_example.cpp
+++ b/libs/endian/example/endian_example.cpp
@@ -16,7 +16,6 @@
 #include 
 #include 
 #include 
-#include 
 #include 
 
 using namespace boost::endian;
@@ -39,9 +38,9 @@ namespace
   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;
 
diff --git a/libs/endian/test/endian_test.cpp b/libs/endian/test/endian_test.cpp
index 2dc71b7..0c2ccef 100644
--- a/libs/endian/test/endian_test.cpp
+++ b/libs/endian/test/endian_test.cpp
@@ -20,7 +20,6 @@
 
 #include 
 #include 
-#include 
 #include 
 
 #include