Endian: docs and examples improvements

git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@51855 b8fc166d-592f-0410-95f2-cb63ce0dd405

libs/integer/example/endian_example.cpp

@@ -2,8 +2,8 @@
 
 //  Copyright Beman Dawes, 2006
 
-//  Distributed under the Boost Software License, Version 1.0. (See accompanying
-//  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//  Distributed under the Boost Software License, Version 1.0.
+//  See http://www.boost.org/LICENSE_1_0.txt
 
 //  See library home page at http://www.boost.org/libs/endian
 
@@ -16,14 +16,13 @@
 #include <cstdio>
 #include <boost/integer/endian.hpp>
 
-using boost::integer::big32_t;
-using boost::integer::little32_t;
+using namespace boost::integer;
 
 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 format and users wishing to write low level code
+  //  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
@@ -39,7 +38,7 @@ namespace
 
 int main()
 {
-  assert( sizeof( header ) == 16 );
+  assert( sizeof( header ) == 16 );  // requirement for interoperability
   
   header h;
 
@@ -48,15 +47,15 @@ int main()
   h.version     = -1;
   h.shape_type  = 0x04030201;
 
-  //  Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is
-  //  typically used for binary file operations. Such I/O is often performed in
-  //  some C++ wrapper class, but to drive home the point that endian integers
-  //  are usually used in fairly low-level code, <cstdio> fopen/fwrite is used
-  //  for I/O in this example.
+  //  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" )) )
+  if ( !(fi = std::fopen( filename, "wb" )) )  // MUST BE BINARY
   {
     std::cout << "could not open " << filename << '\n';
     return 1;

libs/integer/example/endian_hello_world.cpp

@@ -19,8 +19,12 @@ int main()
 {
   int_least32_t v = 0x31323334L;  // = ASCII { '1', '2', '3', '4' }
                                   // value chosen to work on text stream
-  std::cout << "Hello, endian world!\n";
-  std::cout << v << " " << big32_t(v) << " " << little32_t(v) << '\n';
-  std::cout <= v <= ' ' <= big32_t(v) <= ' ' <= little32_t(v) <= '\n';
+  big32_t    b(v);
+  little32_t l(v);
+
+  std::cout << "Hello, endian world!\n\n";
+
+  std::cout << v << ' ' << b << ' ' << l << '\n';
+  std::cout <= v <= ' ' <= b <= ' ' <= l <= '\n';
 }