From e4a92a56b0b62f0c0cc375badc5d9de051814e09 Mon Sep 17 00:00:00 2001 From: Beman Date: Sun, 19 May 2013 08:26:09 -0400 Subject: [PATCH] Semantics complete. --- doc/conversion.html | 155 +++++++++++++++++++++++++++++--------------- 1 file changed, 103 insertions(+), 52 deletions(-) diff --git a/doc/conversion.html b/doc/conversion.html index 9c03e8f..7a50d9e 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -39,7 +39,7 @@ Introduction
Reference
    Synopsis
-    Members
+    Functions
Acknowledgements @@ -60,8 +60,19 @@ provides byte reverse and conversion functions that convert built-in integers, float, and double between native byte ordering and big or little endian byte ordering. User defined types are also supported.

+ + + + +
Caution: Only big and little endianness are supported; + middle endianness is not supported.
+

Reference

+

noexcept is not present for compilers that do not support it. +Boost scoped enum emulation is used for compilers that do not support scoped +enums. Actual functions are inline if appropriate.

+

Synopsis

@@ -81,14 +92,14 @@ namespace endian float reverse_value(float x) noexcept; double reverse_value(double 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; - void reverse(uint32_t& x) noexcept; - void reverse(uint64_t& x) noexcept; - void reverse(float& x) noexcept; - void reverse(double& 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; + void reverse(uint32_t& x) noexcept; + void reverse(uint64_t& x) noexcept; + void reverse(float& x) noexcept; + void reverse(double& x) noexcept; // reverse byte order unless native endianness is big template <class ReversibleValue > @@ -123,8 +134,8 @@ namespace endian template <order From, order To, class Reversible> void convert(Reversible& x) noexcept; - // runtime actual byte-order determination - order actual_order(order o) noexcept; + // runtime effective byte order determination + order effective_order(order x) noexcept; // runtime byte-order conversion template <class ReversibleValue> @@ -136,66 +147,106 @@ namespace endian } // namespace endian } // namespace boost -

Members

-
void reorder(int16_t& x);
-void reorder(int32_t& x);
-void reorder(int64_t& x);
-void reorder(uint16_t& x);
-void reorder(uint32_t& x);
-void reorder(uint64_t& x);
+

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;
+uint32_t reverse_value(uint32_t x) noexcept;
+uint64_t reverse_value(uint64_t x) noexcept;
+float    reverse_value(float x) noexcept;
+double   reverse_value(double x) noexcept;
-

Effects: Reverses the byte order of x.

+

Returns: x, with the order of bytes reversed.

-
void reorder(int16_t source, int16_t& target);
-void reorder(int32_t source, int32_t& target);
-void reorder(int64_t source, int64_t& target);
-void reorder(uint16_t source, uint16_t& target);
-void reorder(uint32_t source, uint32_t& target);
-void reorder(uint64_t source, uint64_t& target);
+
void reverse(int16_t& x) noexcept;
+void reverse(int32_t& x) noexcept;
+void reverse(int64_t& x) noexcept;
+void reverse(uint16_t& x) noexcept;
+void reverse(uint32_t& x) noexcept;
+void reverse(uint64_t& x) noexcept;
+void reverse(float& x) noexcept;
+void reverse(double& x) noexcept;
-

Effects: Copies source to target, - reversing the byte order.

+

Effects: Reverses the order of bytes in x.

-
template <class T> void native_to_big(T& x);
-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);
+
template <class ReversibleValue >
+  ReversibleValue big_endian_value(ReversibleValue x) noexcept; 
+template <class Reversible>
+  void big_endian(Reversible& x) noexcept;
-

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

+

Returns (first form): x if the native byte order is big + endian, otherwise reverse_value(x).

+

Effects (second form): None if the native byte order is big + endian, otherwise reverse(x).

Example:

int32_t x = some-value;
-native_to_big(x); // converts x to big-endian unless
-                  // the native representation is already big-endian
+big_endian(x); // reverses the byte order of x, unless + // the native byte order is 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);
+
template <class ReversibleValue >
+  ReversibleValue little_endian_value(ReversibleValue x) noexcept; 
+template <class Reversible>
+  void little_endian(Reversible& x) noexcept;
-

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

+

Returns (first form): x if the native byte order is little + endian, otherwise reverse_value(x).

+

Effects (second form): None if the native byte order is little + endian, otherwise reverse(x).

+

Example:

+
+ 
int32_t x = some-value;
+int32_t y(little_endian(x));
+// y has been set to x; the byte order is reversed unless
+// the native byte order is little-endian.
+
+
+
template <order From, order To, class ReversibleValue>
+  ReversibleValue convert_value(ReversibleValue from) noexcept;
+template <order From, order To, class Reversible>
+  void convert(Reversible& x) noexcept;
+
+
+

The effective order of an order template parameter + is the same as the order template parameter if the parameter is not + order::native, otherwise it is the constant order::big or + order::little that represents the actual native byte order.

+

Returns (first form): from if From + and To have the same effective order, otherwise + reverse_value(from).

+

Effects (second form): None if From and + To have the same effective order, otherwise reverse(x).

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
+... read an external big-endian value into x +convert<order::big, order::native>(x); // more generic equivalent of big_endian(x);
-

Acknowledgements

-

Tomas Puverle was instrumental in identifying and articulating the need to +

order effective_order(order x) noexcept;
Returns: x if x != order::native, otherwise the order constant for the actual native byte order.
Example:
effective_order(order::big);     // returns order::big
+effective_order(order::little);  // returns order::little
+effective_order(order::native);  // returns order::big if the native order
+                                 // is big-endian, otherwise order::little
template <class ReversibleValue>
+  ReversibleValue convert_value(ReversibleValue from,
+    order from_order, order to_order) noexcept;
+template <class Reversible>
+  void convert(Reversible& x,
+    order from_order, order to_order) noexcept;
Returns (first form): from if effect_order(from_order) == effective_order(to_order), otherwise reverse_value(from).

+  
Effects (second form): None if effect_order(from_order) == effective_order(to_order), otherwise reverse(x).

+  
Example:

+  

+    
int32_t x;
+... read an external value of an endianness know only at runtime into x
+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.

 

-
Last revised:
-18 May, 2013

+
Last revised: 18 May, 2013

 
© Copyright Beman Dawes, 2011

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

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