From 29d65d2e2fefcb5b62000acaeac000a7dc6493ce Mon Sep 17 00:00:00 2001 From: Beman Date: Sun, 19 May 2013 11:07:33 -0400 Subject: [PATCH] Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements. --- doc/conversion.html | 64 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/doc/conversion.html b/doc/conversion.html index 7a50d9e..b243d02 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -67,6 +67,14 @@ ordering. User defined types are also supported.

+

FAQ

+ +

Why are reverse() and reverse_value() templates +in a detail namespace? They are unsafe for general use. Consider reversing +the bytes of a std::pair - the bytes from first +would end up in second and visa versa, and this is totally +wrong!

+

Reference

noexcept is not present for compilers that do not support it. @@ -147,8 +155,48 @@ namespace endian } // namespace endian } // namespace boost -

Functions

-
int16_t  reverse_value(int16_t x) noexcept;
+
Requirements

+
The template definitions in this library refer to various named 
+requirements whose details are set out in this section. 

+
ReversibleValue requirements

+
ReversibleValue is an object or reference type to be 
+supplied by a C++ program instantiating a template; x is a value of 
+type (possibly const) ReversibleValue.

+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
ExpressionReturn typeRequirement

+    
reverse_value(x)

+    
ReversibleValue

+    
The returned value is the value of x with the 
+    order of its constituent bytes reversed.

+
Reversible requirements

+
Reversible is an object or reference type to be 
+supplied by a C++ program instantiating a template; x is a 
+modifiable lvalue of type Reversible.

+
+  
+    
+    
+  
+  
+    
+    
+  
+
ExpressionPost-condition

+    
reverse(x)

+    
The order of the constituent bytes of x are 
+    reversed.

+
Functions

+
int16_t  reverse_value(int16_t x) noexcept;
 int32_t  reverse_value(int32_t x) noexcept;
 int64_t  reverse_value(int64_t x) noexcept;
 uint16_t reverse_value(uint16_t x) noexcept;
@@ -157,9 +205,10 @@ uint64_t reverse_value(uint64_t x) noexcept;
 float    reverse_value(float x) noexcept;
 double   reverse_value(double x) noexcept;

 

-  
Returns: x, with the order of bytes reversed.

+  
Returns: x, with the order of its 
+  constituent bytes reversed.

 

-
void reverse(int16_t& x) noexcept;
+
void reverse(int16_t& x) noexcept;
 void reverse(int32_t& x) noexcept;
 void reverse(int64_t& x) noexcept;
 void reverse(uint16_t& x) noexcept;
@@ -168,9 +217,10 @@ void reverse(uint64_t& x) noexcept;
 void reverse(float& x) noexcept;
 void reverse(double& x) noexcept;

 

-  
Effects: Reverses the order of bytes in x.

+  
Postconditions: The order of the constituent bytes of
+  x are reversed.

 

-
template <class ReversibleValue >
+
template <class ReversibleValue >
   ReversibleValue big_endian_value(ReversibleValue x) noexcept; 
 template <class Reversible>
   void big_endian(Reversible& x) noexcept;

@@ -242,7 +292,7 @@ template <class Reversible>
 convert(x, some_order, order::native);  // convert to native byte order if needed

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

+support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for  boost/endian/detail/intrinsic.hpp.

 

 
Last revised: 18 May, 2013

 
© Copyright Beman Dawes, 2011