diff --git a/libs/endian/doc/conversion.html b/libs/endian/doc/conversion.html index b5111b6..b45bb1c 100644 --- a/libs/endian/doc/conversion.html +++ b/libs/endian/doc/conversion.html @@ -128,24 +128,38 @@ template <class T> void native_to_little(T& x); template <class T> void big_to_native(T& x); template <class T> void little_to_native(T& x);
-

Effects: If the native byte ordering and indicated byte - ordering are different, reorder(x), otherwise no effect.

+

Effects: If the native byte ordering and byte + ordering indicated by the function name are different, reorder(x), otherwise no effect.

+

Example:

+
+ 
int32_t x = some-value;
+native_to_big(x); // converts x to big-endian unless
+                  // the native representation is already big-endian
+ 
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);
-

Effects: If the native byte ordering and indicated byte - ordering are different, reorder(source, target), otherwise +

Effects: If the native byte ordering and byte + ordering indicated by the function name are different, reorder(source, target), otherwise target = source.

+

Example:

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

Acknowledgements

Tomas Puverle was instrumental in identifying and articulating the need to support endian conversion as separate from endian types.

Last revised: -04 September, 2011

+05 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 216cf15..3e9c014 100644 --- a/libs/endian/doc/integers.html +++ b/libs/endian/doc/integers.html @@ -40,7 +40,7 @@ Introduction
- Hello endian world
+ Example
Limitations
Feature set
Typedefs
@@ -50,7 +50,6 @@ Synopsis
    Members
FAQ
- Example
Design
Experience
Motivating use cases
@@ -97,35 +96,76 @@ arithmetic operators are +, +=, -, >>=. Binary relational operators are ==, !=, <, <=, >, >=.

Automatic conversion is provided to the underlying integer value type.

-

Hello endian world

+

Example

+

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

- 
#include <boost/integer/endian.hpp>
-#include <boost/integer/endian_binary_stream.hpp>
-#include <boost/binary_stream.hpp>
-#include <iostream>
+  
#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
 
-  std::cout << "Hello, endian world!\n\n";
+  header h;
 
-  std::cout << v << ' ' << b << ' ' << l << '\n';
-  std::cout <= v <= ' ' <= b <= ' ' <= l <= '\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;
+  }
+
+  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;
 }
-

On a little-endian CPU, this program outputs:

+

After compiling and executing endian_example.cpp, +a hex dump of test.dat shows:

- 
Hello, endian world!
-
-825373492 825373492 825373492
-4321 1234 4321
+ 
0102 0304 0000 0010 ffff ffff 0403 0201

Limitations

Requires <climits> CHAR_BIT == 8. If CHAR_BIT @@ -470,76 +510,6 @@ incrementing a variable in a record. It is very convenient to write:

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

Example

-

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

-
- 
#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;
-}
-
-

After compiling and executing endian_example.cpp, a hex dump of test.dat shows:

-
- 
0403 0201 0000 0010 ffff ffff 0102 0304
-

Design considerations for Boost.Endian integers