diff --git a/doc/conversion.html b/doc/conversion.html index 636fbab..ef10866 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -1,4 +1,4 @@ - + @@ -45,7 +45,7 @@ Reference
    Synopsis
    Requirements
-      Reversible
+      EndianReversible
      Customization for UDTs
Functions
@@ -98,6 +98,7 @@ namespace endian native = implementation-defined-as-big-or-little }; + TODO: Add overloads for char, wchar_t, char16_t, char32_t int8_t endian_reverse(int8_t x) noexcept; int16_t endian_reverse(int16_t x) noexcept; int32_t endian_reverse(int32_t x) noexcept; @@ -109,35 +110,35 @@ namespace endian float endian_reverse(float x) noexcept; double endian_reverse(double x) noexcept; - template <class Reversible> - Reversible big_to_native(Reversible x) noexcept; - template <class Reversible> - Reversible native_to_big(Reversible x) noexcept; - template <class Reversible> - Reversible little_to_native(Reversible x) noexcept; - template <class Reversible> - Reversible native_to_little(Reversible x) noexcept; - template <order O1, order O2, class Reversible> - Reversible conditional_reverse(Reversible x) noexcept; - template <class Reversible> - Reversible conditional_reverse(Reversible x, + template <class EndianReversible> + EndianReversible big_to_native(EndianReversible x) noexcept; + template <class EndianReversible> + EndianReversible native_to_big(EndianReversible x) noexcept; + template <class EndianReversible> + EndianReversible little_to_native(EndianReversible x) noexcept; + template <class EndianReversible> + EndianReversible native_to_little(EndianReversible x) noexcept; + template <order O1, order O2, class EndianReversible> + EndianReversible conditional_reverse(EndianReversible x) noexcept; + template <class EndianReversible> + EndianReversible conditional_reverse(EndianReversible x, order order1, order order2) noexcept; - template <class Reversible> - void endian_reverse_inplace(Reversible& x) noexcept; + template <class EndianReversible> + void endian_reverse_inplace(EndianReversible& x) noexcept; - template <class Reversible> - void big_to_native_inplace(Reversible& x) noexcept; - template <class Reversible> - void native_to_big_inplace(Reversible& x) noexcept; - template <class Reversible> - void little_to_native_inplace(Reversible& x) noexcept; - template <class Reversible> - void native_to_little_inplace(Reversible& x) noexcept; - template <order O1, order O2, class Reversible> - void conditional_reverse_inplace(Reversible& x) noexcept; - template <class Reversible> - void conditional_reverse_inplace(Reversible& x, + template <class EndianReversibleInplace> + void big_to_native_inplace(EndianReversibleInplace& x) noexcept; + template <class EndianReversibleInplace> + void native_to_big_inplace(EndianReversibleInplace& x) noexcept; + template <class EndianReversibleInplace> + void little_to_native_inplace(EndianReversibleInplace& x) noexcept; + template <class EndianReversibleInplace> + void native_to_little_inplace(EndianReversibleInplace& x) noexcept; + template <order O1, order O2, class EndianReversibleInplace> + void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; + template <class EndianReversibleInplace> + void conditional_reverse_inplace(EndianReversibleInplace& x, order order1, order order2) noexcept; } // namespace endian @@ -146,77 +147,91 @@ namespace endian constant native as big on big endian platforms and little on little endian platforms.

+

Definitions

+

The standard integral types (C++std 3.9.1) except bool, +and the floating point types float and double are +collectively called the endian types.

Requirements

-

Template argument Reversible requirements

-

This subsection describes names that are used to specify constraints on -template arguments.

-

User-defined types may be used in the function templates in this header only -if they meet these requirements.

-

Reversible is an object type to be supplied by a C++ program -instantiating a template.

+

Template argument requirements

+

The template definitions in the boost/endian/conversion.hpp +header refer to various named requirements whose details are set out in the +tables in this subsection. In these tables, T is an object or +reference type to be supplied by a C++ program instantiating a template; x +is a value of type (possibly const) T; mlx is a +modifiable lvalue of type T.

- - - + - - - + + + - - - + + + + +
ExpressionMeaning of xRequirementsEndianReversible + requirements (in addition to CopyConstructible)
-

endian_reverse(x)

 - x is a value of a possibly const type convertible - to Reversible. -

Returns the value of x with the - order of its constituent bytes reversed.

ExpressionReturn
+ type		Requirements
- endian_reverse_inplace(x) - x is a -modifiable lvalue of type Reversible. - The order of the constituent bytes of x are - reversed.endian_reverse(x)T T is an endian type or a class type.

If T is + an endian type, returns the value of x with the order of bytes + reversed.

+

If T is an class type, the function:

+
    +
  • Returns the value of x + with the order of bytes reversed for all data members of types or arrays of + types that meet the EndianReversible requirements, and;
    • +
  • Is a non-member function in the same namespace as T that +can be found by argument dependent lookup (ADL).
    • +
+
+

 

+ + + + + + + + + + +
EndianReversibleInplace + requirements (in addition to CopyConstructible)
ExpressionRequirements
endian_reverse_inplace(mlx) T is an endian type or a class type.

If T is + an endian type, reverses the order of bytes in mlx.

+

If T is an class type, the function:

+
    +
  • Reverses the order of bytes of all data members of mlx + that have types or arrays of + types that meet the EndianReversible or EndianReversibleInplace + requirements, and;
    • +
  • Is a non-member function in the same namespace as T that +can be found by argument dependent lookup (ADL). 
    • +
+
-
- -

[Note: A user-defined type meets these requirements by defining a -non-member function in the same namespace as the UDT itself so that the function -can be found by argument dependent lookup (ADL).  —end note]

-

[Note: Because there is a function template for endian_reverse_inplace that calls endian_reverse, only endian_reverse -is required for a user-defined type to meet the Reversible -requirements. User-defined types may provide endian_reverse_inplace -for improved efficiency. —end note]

- -

This still isn't right. There are -really separate Reversible and -ReversibleHere requirements, and -the endian_reverse_here -template's type should be Reversible. See the udt_conversion_example for a type -that is ReversibleHere but not Reversible and works just fine.

- -
+is required for a user-defined type to meet the EndianReversibleInplace +requirements. Although User-defined types are not required to supply an endian_reverse_inplace +function, doing so may improved efficiency.  —end note]

Customization points for user-defined types (UDTs)

-

This subsection describes requirements on the endian library's own -implementation.

+

This subsection describes requirements on the Endian library's implementation.

-

The endianness reversal function templates that return values are +

The library's function templates requiring +EndianReversible are required to perform reversal of endianness if needed by making an unqualified -call to endian_reverse(argument), as described in the -preceding table.

+call to endian_reverse().

-

The endianness reversal function templates that modify their argument in -place, except endian_reverse_inplace itself, are required to perform reversal of endianness if needed by making an -unqualified call to endian_reverse_inplace(argument), -as described in the preceding table.

+

The library's function templates requiring +EndianReversibleInplace are required to perform reversal of endianness if needed by making an +unqualified call to endian_reverse_inplace().

See udt_conversion_example.cpp for an example user-defined type.

@@ -233,90 +248,93 @@ uint64_t endian_reverse(uint64_t x) noexcept; float endian_reverse(float x) noexcept; double endian_reverse(double x) noexcept;
-

Returns: x, with the order of its +

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

+

Remarks: Meet the EndianReversible requirements.

+

[Note: The Boost.Endian library does not provide overloads for the C++ standard library + supplied types. —end note]

-
template <class Reversible>
-Reversible big_to_native(Reversible x) noexcept;
+
template <class EndianReversible>
+EndianReversible big_to_native(EndianReversible x) noexcept;

Returns: conditional_reverse<order::big, order::native>(x).

-
template <class Reversible>
-Reversible native_to_big(Reversible x) noexcept;
+
template <class EndianReversible>
+EndianReversible native_to_big(EndianReversible x) noexcept;

Returns: conditional_reverse<order::native, order::big>(x).

-
template <class Reversible>
-Reversible little_to_native(Reversible x) noexcept;
+
template <class EndianReversible>
+EndianReversible little_to_native(EndianReversible x) noexcept;

Returns: conditional_reverse<order::little, order::native>(x).

-
template <class Reversible>
-Reversible native_to_little(Reversible x) noexcept;
+
template <class EndianReversible>
+EndianReversible native_to_little(EndianReversible x) noexcept;

Returns: conditional_reverse<order::native, order::little>(x).

-
template <order O1, order O2, class Reversible>
-Reversible conditional_reverse(Reversible x) noexcept;
+
template <order O1, order O2, class EndianReversible>
+EndianReversible conditional_reverse(EndianReversible x) noexcept;

Returns: x if O1 == O2, otherwise endian_reverse(x).

Remarks: Whether x or endian_reverse(x) is to be returned shall be determined at compile time.

-
template <class Reversible>
-Reversible conditional_reverse(Reversible x,
+
template <class EndianReversible>
+EndianReversible conditional_reverse(EndianReversible x,
       order order1, order order2) noexcept; 

     

         
Returns: order1 == order2 ? x : endian_reverse(x).

     

       
-
template <class Reversible>
-void endian_reverse_inplace(Reversible& x) noexcept; 

+
template <class EndianReversible>
+void endian_reverse_inplace(EndianReversible& x) noexcept; 

 
 

         
Effects: x = endian_reverse(x).

     

 
-
template <class Reversible>
-void big_to_native_inplace(Reversible& x) noexcept; 

+
template <class EndianReversibleInplace>
+void big_to_native_inplace(EndianReversibleInplace& x) noexcept; 

 

         

             Effects: conditional_reverse_inplace<order::big, 
             order::native>(x).

     

-
template <class Reversible>
-void native_to_big_inplace(Reversible& x) noexcept; 

+
template <class EndianReversibleInplace>
+void native_to_big_inplace(EndianReversibleInplace& x) noexcept; 

 

         

             Effects: conditional_reverse_inplace<order::native, 
             order::big>(x).

     

-
template <class Reversible>
-void little_to_native_inplace(Reversible& x) noexcept; 

+
template <class EndianReversibleInplace>
+void little_to_native_inplace(EndianReversibleInplace& x) noexcept; 

 

         

             Effects: conditional_reverse_inplace<order::little, order::native>(x).

     

-
template <class Reversible>
-void native_to_little_inplace(Reversible& x) noexcept; 

+
template <class EndianReversibleInplace>
+void native_to_little_inplace(EndianReversibleInplace& x) noexcept; 

 

         

             Effects: conditional_reverse_inplace<order::native, 
             order::little>(x).

     

-
template <order O1, order O2, class Reversible>
-void conditional_reverse_inplace(Reversible& x) noexcept; 
 
+
template <order O1, order O2, class EndianReversibleInplace>
+void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; 
 
 

         
Effects: None if O1 == O2, otherwise
         endian_reverse_inplace(x).

         
Remarks: Which effect applies shall be determined at compile time.

     

-
template <class Reversible>
-void conditional_reverse_inplace(Reversible& x,
+
template <class EndianReversibleInplace>
+void conditional_reverse_inplace(EndianReversibleInplace& x,
      order order1, order order2) noexcept; 

 
 
@@ -348,7 +366,7 @@ Pierre Talbot provided the int8_t endian_reverse() and templated
 endian_reverse_inplace() implementations.

 

 
Last revised: 
-10 December, 2014

+11 December, 2014

 
© Copyright Beman Dawes, 2011, 2013

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

 
diff --git a/include/boost/endian/conversion.hpp b/include/boost/endian/conversion.hpp
index fad465e..417c708 100644
--- a/include/boost/endian/conversion.hpp
+++ b/include/boost/endian/conversion.hpp
@@ -66,33 +66,35 @@ namespace endian
   inline double   endian_reverse(double x) BOOST_NOEXCEPT;
 
   //  reverse byte order unless native endianness is big
-  template 
-    inline Reversible  big_to_native(Reversible  x) BOOST_NOEXCEPT;
+  template 
+    inline EndianReversible  big_to_native(EndianReversible  x) BOOST_NOEXCEPT;
     //  Returns: x if native endian order is big, otherwise endian_reverse(x)
-  template 
-    inline Reversible  native_to_big(Reversible  x) BOOST_NOEXCEPT;
+  template 
+    inline EndianReversible  native_to_big(EndianReversible  x) BOOST_NOEXCEPT;
     //  Returns: x if native endian order is big, otherwise endian_reverse(x)
 
   //  reverse byte order unless native endianness is little
-  template 
-    inline Reversible  little_to_native(Reversible  x) BOOST_NOEXCEPT;
+  template 
+    inline EndianReversible  little_to_native(EndianReversible  x) BOOST_NOEXCEPT;
     //  Returns: x if native endian order is little, otherwise endian_reverse(x)
-  template 
-    inline Reversible  native_to_little(Reversible  x) BOOST_NOEXCEPT;
+  template 
+    inline EndianReversible  native_to_little(EndianReversible  x) BOOST_NOEXCEPT;
     //  Returns: x if native endian order is little, otherwise endian_reverse(x)
 
   //  generic conditional reverse byte order
-  template 
-  inline Reversible  conditional_reverse(Reversible from) BOOST_NOEXCEPT;
+  template 
+      inline EndianReversible  conditional_reverse(EndianReversible from) BOOST_NOEXCEPT;
     //  Returns: If From == To have different values, from.
     //           Otherwise endian_reverse(from).
     //  Remarks: The From == To test, and as a consequence which form the return takes, is
     //           is determined at compile time.
 
   //  runtime conditional reverse byte order
-  template 
-  inline Reversible  conditional_reverse(Reversible from,
-    BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT;
+  template 
+    inline EndianReversible  conditional_reverse(EndianReversible from,
+      BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order)
+        BOOST_NOEXCEPT;
       //  Returns: from_order == to_order ? from : endian_reverse(from).
 
   //------------------------------------------------------------------------------------//
@@ -123,33 +125,33 @@ namespace endian
   //------------------------------------------------------------------------------------//
 
   //  reverse in place
-  template 
-    inline void endian_reverse_inplace(Value& x) BOOST_NOEXCEPT;
+  template 
+    inline void endian_reverse_inplace(EndianReversible& x) BOOST_NOEXCEPT;
     //  Effects: x = endian_reverse(x)
 
   //  reverse in place unless native endianness is big
-  template 
-    inline void big_to_native_inplace(Reversible& x) BOOST_NOEXCEPT;
+  template 
+    inline void big_to_native_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT;
     //  Effects: none if native byte-order is big, otherwise endian_reverse_inplace(x)
-  template 
-    inline void native_to_big_inplace(Reversible& x) BOOST_NOEXCEPT;
+  template 
+    inline void native_to_big_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT;
     //  Effects: none if native byte-order is big, otherwise endian_reverse_inplace(x)
 
   //  reverse in place unless native endianness is little
-  template 
-    inline void little_to_native_inplace(Reversible& x) BOOST_NOEXCEPT;
+  template 
+    inline void little_to_native_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT;
     //  Effects: none if native byte-order is little, otherwise endian_reverse_inplace(x);
-  template 
-    inline void native_to_little_inplace(Reversible& x) BOOST_NOEXCEPT;
+  template 
+    inline void native_to_little_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT;
     //  Effects: none if native byte-order is little, otherwise endian_reverse_inplace(x);
 
   //  generic conditional reverse in place
-  template 
-  inline void conditional_reverse_inplace(Reversible& x) BOOST_NOEXCEPT; 
+  template 
+  inline void conditional_reverse_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT; 
 
   //  runtime reverse in place
-  template 
-  inline void conditional_reverse_inplace(Reversible& x,
+  template 
+  inline void conditional_reverse_inplace(EndianReversibleInplace& x,
     BOOST_SCOPED_ENUM(order) from_order,  BOOST_SCOPED_ENUM(order) to_order)
     BOOST_NOEXCEPT;
 
@@ -296,8 +298,8 @@ namespace endian
     return detail::std_endian_reverse(x);
   }
 
-  template 
-  inline Reversible  big_to_native(Reversible  x) BOOST_NOEXCEPT
+  template 
+  inline EndianReversible  big_to_native(EndianReversible  x) BOOST_NOEXCEPT
   {
 #   ifdef BOOST_BIG_ENDIAN
     return x;
@@ -306,8 +308,8 @@ namespace endian
 #   endif
   }
 
-  template 
-  inline Reversible  native_to_big(Reversible  x) BOOST_NOEXCEPT
+  template 
+  inline EndianReversible  native_to_big(EndianReversible  x) BOOST_NOEXCEPT
   {
 #   ifdef BOOST_BIG_ENDIAN
     return x;
@@ -316,8 +318,8 @@ namespace endian
 #   endif
   }
 
-  template 
-  inline Reversible  little_to_native(Reversible  x) BOOST_NOEXCEPT
+  template 
+  inline EndianReversible  little_to_native(EndianReversible  x) BOOST_NOEXCEPT
   {
 #   ifdef BOOST_LITTLE_ENDIAN
     return x;
@@ -326,8 +328,8 @@ namespace endian
 #   endif
   }
 
-  template 
-  inline Reversible  native_to_little(Reversible  x) BOOST_NOEXCEPT
+  template 
+  inline EndianReversible  native_to_little(EndianReversible  x) BOOST_NOEXCEPT
   {
 #   ifdef BOOST_LITTLE_ENDIAN
     return x;
@@ -340,7 +342,7 @@ namespace endian
   {
     //  Primary template and specializations to support endian_reverse().
     //  See rationale in endian_reverse() below.
-    template 
+    template 
       class value_converter ;  // primary template
     template  class value_converter 
       {public: T operator()(T x) BOOST_NOEXCEPT {return x;}};
@@ -353,18 +355,18 @@ namespace endian
   }
 
   //  generic conditional reverse
-  template 
-  inline Reversible  conditional_reverse(Reversible from) BOOST_NOEXCEPT  {
+  template 
+  inline EndianReversible  conditional_reverse(EndianReversible from) BOOST_NOEXCEPT  {
     //  work around lack of function template partial specialization by instantiating
     //  a function object of a class that is partially specialized on the two order
     //  template parameters, and then calling its operator().
-    detail::value_converter  tmp;
+    detail::value_converter  tmp;
     return tmp(from);
   }
 
   //  runtime conditional reverse
-  template 
-  inline Reversible  conditional_reverse(Reversible  from,
+  template 
+  inline EndianReversible  conditional_reverse(EndianReversible  from,
     BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT
   {
     return from_order == to_order ? from : endian_reverse(from);
@@ -375,41 +377,41 @@ namespace endian
 //--------------------------------------------------------------------------------------//
 
   //  reverse in place
-  template 
-  inline void endian_reverse_inplace(Value& x) BOOST_NOEXCEPT
+  template 
+  inline void endian_reverse_inplace(EndianReversible& x) BOOST_NOEXCEPT
   {
     x = endian_reverse(x);
   }
 
-  template 
+  template 
 #   ifdef BOOST_BIG_ENDIAN
-  inline void big_to_native_inplace(Reversible&) BOOST_NOEXCEPT {}
+  inline void big_to_native_inplace(EndianReversibleInplace&) BOOST_NOEXCEPT {}
 #   else
-  inline void big_to_native_inplace(Reversible& x) BOOST_NOEXCEPT
+  inline void big_to_native_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT
     { endian_reverse_inplace(x); }
 #   endif
-  template 
+  template 
 #   ifdef BOOST_BIG_ENDIAN
-  inline void native_to_big_inplace(Reversible&) BOOST_NOEXCEPT {}
+  inline void native_to_big_inplace(EndianReversibleInplace&) BOOST_NOEXCEPT {}
 #   else
-  inline void native_to_big_inplace(Reversible& x) BOOST_NOEXCEPT
+  inline void native_to_big_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT
   {
     endian_reverse_inplace(x);
   }
 #   endif
 
-  template 
+  template 
 #   ifdef BOOST_LITTLE_ENDIAN
-  inline void little_to_native_inplace(Reversible&) BOOST_NOEXCEPT {}
+  inline void little_to_native_inplace(EndianReversibleInplace&) BOOST_NOEXCEPT {}
 #   else
-  inline void little_to_native_inplace(Reversible& x) BOOST_NOEXCEPT
+  inline void little_to_native_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT
     { endian_reverse_inplace(x); }
 #   endif
-  template 
+  template 
 #   ifdef BOOST_LITTLE_ENDIAN
-  inline void native_to_little_inplace(Reversible&) BOOST_NOEXCEPT {}
+  inline void native_to_little_inplace(EndianReversibleInplace&) BOOST_NOEXCEPT {}
 #   else
-  inline void native_to_little_inplace(Reversible& x) BOOST_NOEXCEPT
+  inline void native_to_little_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT
   {
     endian_reverse_inplace(x);
   }
@@ -420,7 +422,7 @@ namespace endian
     //  Primary template and specializations support generic 
     //  endian_reverse_inplace().
     //  See rationale in endian_reverse_inplace() below.
-    template 
+    template 
       class converter;  // primary template
     template  class converter
       {public: void operator()(T&) BOOST_NOEXCEPT {/*no effect*/}};
@@ -433,19 +435,19 @@ namespace endian
   }  // namespace detail
 
   //  generic conditional reverse in place
-  template 
-  inline void conditional_reverse_inplace(Reversible& x) BOOST_NOEXCEPT
+  template 
+  inline void conditional_reverse_inplace(EndianReversibleInplace& x) BOOST_NOEXCEPT
   {
     //  work around lack of function template partial specialization by instantiating
     //  a function object of a class that is partially specialized on the two order
     //  template parameters, and then calling its operator().
-    detail::converter tmp;
+    detail::converter tmp;
     tmp(x);  // call operator ()
   }
 
   //  runtime reverse in place
-  template 
-  inline void conditional_reverse_inplace(Reversible& x,
+  template 
+  inline void conditional_reverse_inplace(EndianReversibleInplace& x,
     BOOST_SCOPED_ENUM(order) from_order,  BOOST_SCOPED_ENUM(order) to_order)
     BOOST_NOEXCEPT
   {
diff --git a/test/endian_operations_test.cpp b/test/endian_operations_test.cpp
index 18dedb5..de9e76e 100644
--- a/test/endian_operations_test.cpp
+++ b/test/endian_operations_test.cpp
@@ -90,7 +90,7 @@ struct construct
   static void test()
   {
     T2 o2(1);
-    T1 o1(o2);
+    T1 o1(o2);   // TODO: does this make sense for char types?
     ++o1;  // quiet gcc unused variable warning
   }
 };