From ee750c0ec8edeff162542cc7a3d3d6be6566bdf9 Mon Sep 17 00:00:00 2001 From: Beman Date: Mon, 20 May 2013 08:47:38 -0400 Subject: [PATCH] Minor edits to conversion docs. Edits plus add Advantages table to index.html. --- doc/conversion.html | 18 +++++------ doc/index.html | 74 ++++++++++++++++++++++++++++++++++++--------- 2 files changed, 68 insertions(+), 24 deletions(-) diff --git a/doc/conversion.html b/doc/conversion.html index 4f83d2a..b9e8dd1 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -37,7 +37,7 @@ Introduction
- FAQ
+ conversion.hpp FAQ
Reference
    Synopsis
    Requirements
@@ -79,7 +79,7 @@ ordering. User defined types are also supported.

-

FAQ

+

conversion.hpp FAQ

Is the implementation header only?

@@ -98,7 +98,7 @@ below.

-

Why are reverse() and reverse_value() templates +

Why are the template versions of reverse() and reverse_value() in a detail namespace?

@@ -110,14 +110,14 @@ wrong!

-

Why are both value returning and modify_in_place functions provided?

+

Why are both value returning and modify-in-place functions provided?

-

Value returning functions are the standard idiom for functions that compute a -value. Modification in place functions allow cleaner code in many real-world -endian use cases and are more efficient for user defined types that have many -members such as string data that do not need to be reversed. Thus both are +

Returning the result by value is the standard C and C++ idiom for functions that compute a +value from an argument. Modify-in-place functions allow cleaner code in many real-world +endian use cases and are more efficient for user defined types that have +members such as string data that do not need to be reversed. Thus both forms are provided.

@@ -138,7 +138,7 @@ point formats.

Only 16-bit, 32-bit, and 64-bit integers are supported. No tests have been -performed on machines that use something other than two's complement arithmetic.

+performed on machines that do not use two's complement arithmetic.

diff --git a/doc/index.html b/doc/index.html index 3e68295..a15b005 100644 --- a/doc/index.html +++ b/doc/index.html @@ -116,31 +116,75 @@ endianness. But when exchanging binary integers with other computer systems, whe 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 two facilities for dealing with endianness.

The library provides two approaches to dealing with integer endianness:

-

Endian conversions for native integers - The application uses the -built-in integer types, and calls the provided conversion functions to convert -byte ordering as needed. Both mutating and non-mutating conversions are supplied, and -each comes in unconditional and conditional variants. This approach is simple -and usually more efficient, but is less flexible in terms of size and alignment, can be -hard-to-manage and error-prone in code with many logical paths involving endianness transitions, -and can foster very hard to debug logic errors.

+

Endian conversions - The application +uses the built-in integer and floating point types, and calls the provided +conversion functions to convert byte ordering as needed. Both mutating and +non-mutating conversions are supplied, and each comes in unconditional and +conditional variants. Type long double is not currently supported.

-

Endian integer types - The application uses the provided endian types +

Endian types - The application uses the provided endian types which mimic the -built-in integer types. For example, big32_t or little64_t. -This approach is also simple, but can be less efficient. Types with lengths of -1-8 bytes are supported, rather than just 1, 2, 4, and 8 bytes. Strict alignment -requirements are avoided, and this may allow data to be packed more tightly.

+built-in integer types. For example, big32_t or little64_t. Types with lengths of +1-8 bytes are supported, rather than just  2, 4, and 8 bytes. There are no alignment +requirements. Floating point types are not currently supported.

Boost Endian is a header-only library.

+

Choosing between endian types and endian +conversion functions

+ +

Which approach is best for dealing with endianness depends on the +application.

+ + + + + + + + + + + + + +
Advantages
Endian typesEndian conversion functions
+
    +
  • Mimic the built-in types. This can simplify use and eliminate logic + errors since there is no need to reason about the current endianness of + variables.
    + 
    • +
  • 1, 2, 3, 4, 5, 6, 7, and 8 byte integers are supported. Use of 3, 5, + 6, or 7 byte integers can reduce internal and external space usage and + save I/O time.
    + 
    • +
  • Alignment is not required. This can eliminate padding bytes in + structures, reducing internal and external space usage and saving I/O + time.
    • +
+ 		+
    +
  • Already familiar to developers who have been using C conversion + functions for years.
    + 
    • +
  • Uses less CPU time, particularly if each variable is used many times + relative to I/O of the variable.
    + 
    • +
  • Easier to pass structures to third-party libraries expecting a + specific structure format.
    + 
    • +
  • Supports float and double.
    • +
+
+

Acknowledgements

Comments and suggestions were received from @@ -155,13 +199,13 @@ Marsh Ray, Martin Bonner, Matias Capeletto, Neil Mayhew, Phil Endecott, Rene Rivera, -Roland Schwarz, Scott McMurray, +Robert Stewart, Roland Schwarz, Scott McMurray, Sebastian Redl, Tomas Puverle, Vincente Botet, and Yuval Ronen.

Last revised: -19 May, 2013

+20 May, 2013

© Copyright Beman Dawes, 2011

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