From 28fd6ef4b0d08683d1aa2a42a8e515a9c75d9c1d Mon Sep 17 00:00:00 2001 From: Beman Date: Tue, 9 Dec 2014 07:04:48 -0500 Subject: [PATCH] Bring docs in sync with implementation. Still somewhat incomplete. --- doc/arithmetic.html | 17 ++-- doc/bikeshed.txt | 21 ++++- doc/buffers.html | 80 ++++++++++------ doc/conversion.html | 177 ++++++++++++++++++------------------ doc/index.html | 9 +- doc/mini_review_topics.html | 7 +- 6 files changed, 175 insertions(+), 136 deletions(-) diff --git a/doc/arithmetic.html b/doc/arithmetic.html index c150df3..be79f3c 100644 --- a/doc/arithmetic.html +++ b/doc/arithmetic.html @@ -71,6 +71,7 @@ <boost/endian/conversion.hpp>
+ <boost/endian/buffers.hpp>
<boost/endian/arithmetic.hpp> @@ -375,19 +376,21 @@ usual operations on integers are supplied.

enum class align {no, yes}; template <order Order, class T, std::size_t n_bits, align A = align::no> - class endian + class endian_arithmetic + : public endian_buffer<Order, T, n_bits, A> { public: typedef T value_type; // if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 POD's are not // available then these two constructors will not be present - endian() noexcept = default; - endian(T v) noexcept; + endian_arithmetic() noexcept = default; + endian_arithmetic(T v) noexcept; - endian& operator=(T v) noexcept; - operator T() const noexcept; - const char* data() const noexcept; + endian_arithmetic& operator=(T v) noexcept; + operator value_type() const noexcept; + value_type value() const noexcept; // exposition only; see endian_buffer + const char* data() const noexcept; // exposition only; see endian_buffer // arithmetic operations // note that additional operations are provided by the value_type @@ -678,7 +681,7 @@ differs from endian representation size. Vicente Botet and other reviewers suggested supporting floating point types.

Last revised: -19 November, 2014

+05 December, 2014

© Copyright Beman Dawes, 2006-2009, 2013

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

diff --git a/doc/bikeshed.txt b/doc/bikeshed.txt index 891784d..1ef2309 100644 --- a/doc/bikeshed.txt +++ b/doc/bikeshed.txt @@ -3,12 +3,17 @@ Conversion function naming bikeshed return-by-value modify-argument ------------------ --------------- -reverse_endianness reverse_endianness_in_place <------- +reverse_endianness reverse_endianness_in_place " reverse_endianness_arg +endian_reverse endian_reverse_in_place + " endian_reverse_here + " endian_reverse_this + " endian_reverse_self + " endian_reverse_arg + " endian_reverse_in <------ reverse reverse_in_place reverse_endian reverse_endian_in_place -endian_reverse endian_reverse_in_place swap_endianness swap_endianness_in_place swap_endian swap_endian_in_place @@ -31,7 +36,16 @@ Key points: the various conditional functions instead. So explicitness is more important than brevity. +big_to_native native_to_big reverse_unless_native_big little_to_native native_to_little reverse_unless_native_little + reverse_if_not_big + reverse_if_little + reverse_unless_big +big_to_host host_to_big reverse_unless_host_big + reverse_if_host_little +be_to_ne ne_to_be + +from_big, to_big, reverse_unless_big merriam-webster.com/dictionary @@ -48,4 +62,7 @@ flip (verb) : to cause (something) to turn or turn over quickly : to move (something) with a quick light movement + + + \ No newline at end of file diff --git a/doc/buffers.html b/doc/buffers.html index c747a54..f6dbb33 100644 --- a/doc/buffers.html +++ b/doc/buffers.html @@ -1,4 +1,4 @@ - + @@ -64,26 +64,34 @@ +

<boost/endian/conversion.hpp>
+ <boost/endian/buffers.hpp>
<boost/endian/arithmetic.hpp>

Introduction

-

Header boost/endian/buffers.hpp -provides portable integer and floating-point binary buffer types with control over -byte order, value type, size, and alignment independent of the native computer -architecture. Typedefs provide easy-to-use names -for common configurations. Use cases almost always involve I/O, either via files or -network connections.

-

Although data portability is the primary motivation, these byte-holders may -also be used to reduce memory use, file size, or network activity since they -also -provide binary numeric sizes not otherwise available.

-

The byte order of arithmetic types is traditionally called endianness. See the +

The internal byte order of arithmetic types is traditionally called endianness. See the Wikipedia for a full exploration of endianness, including definitions of big endian and little endian.

+

Header boost/endian/buffers.hpp +provides endian_buffer, a portable endian integer and floating-point binary buffer +class template with control over +byte order, value type, size, and alignment independent of the platform's native +endianness. Typedefs provide easy-to-use names +for common configurations.

+

Use cases primarily involve data portability, either via files or network +connections, but these byte-holders may +also be used to reduce memory use, file size, or network activity since they + +provide binary numeric sizes not otherwise available.

+

Class endian_buffer is aimed at users who wish +explicit control over when endianness conversions occur. It also serves as the +base class for the endian_arithmetic +class template, which is aimed at users who wish fully automatic endianness +conversion and direct support for all normal arithmetic operations.

Example

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

@@ -360,13 +368,11 @@ usual operations on integers are supplied.

public: typedef T value_type; - // if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 POD's are not - // available then these two constructors will not be present endian_buffer() noexcept = default; explicit endian_buffer(T v) noexcept; endian_buffer& operator=(T v) noexcept; - value_type value() const noexcept; + value_type value() const noexcept; const char* data() const noexcept; protected: implementaton-defined endian_value; // for exposition only @@ -489,35 +495,49 @@ requirements imposed by the Nbits and Align template parameters.  The CHAR_BIT macro is defined in <climits>. The only value of CHAR_BIT that -is required to be supported is 8.

+is required to be supported is 8.

+

Template parameter T is +required to be a standard integer type (C++std, 3.9.1) and +sizeof(T)*CHAR_BIT is required to be +greater or equal to Nbits.

Members

-
- 
endian_buffer() = default;  // C++03: endian(){}
-
+ 
endian_buffer() noexcept = default;

Effects: Constructs an object of type endian_buffer<Order, T, Nbits, Align>.

-
explicit endian_buffer(T v);
+
explicit endian_buffer(T v) noexcept;

Effects: Constructs an object of type endian_buffer<Order, T, Nbits, Align>.

-

Postcondition: value() == v.

+

Postcondition: value() == v & mask, where mask +is a constant of type value_type with Nbits low-order +bits set to one.

+

Remarks: If Align is align::yes then +endianness conversion if required is performed by +boost::endian::reverse_endianness.

-
endian_buffer& operator=(T v);
+
endian_buffer& operator=(T v) noexcept;
-

Postcondition: value() == v.

+

Postcondition: value() == v & mask, where mask + is a constant of type value_type with Nbits + low-order bits set to one..

Returns: *this.

+

Remarks: If Align is align::yes then +endianness conversion if required is performed by +boost::endian::reverse_endianness.

-
value_type value() const;
+
value_type value() const noexcept;
-

Returns: The current value stored in *this, converted to -value_type.

+

Returns: endian_value, converted to value_type +if necessary and having the endianness of the native platform.

+

Remarks: If Align is align::yes then +endianness conversion if required is performed by +boost::endian::reverse_endianness.

-
const char* data() const;
+
const char* data() const noexcept;
-

Returns: A pointer to the first byte of the endian binary value stored -in *this.

+

Returns: A pointer to the first byte of endian_value.

FAQ

@@ -597,7 +617,7 @@ any Boost object libraries.

Last revised: -05 December, 2014

+06 December, 2014

© Copyright Beman Dawes, 2006-2009, 2013

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

diff --git a/doc/conversion.html b/doc/conversion.html index 4054e00..f2a309b 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -1,4 +1,4 @@ - + @@ -45,7 +45,10 @@ Reference
    Synopsis
    Requirements
-    Functions
+      Reversible
+      Customization for + UDTs
+ Functions
FAQ
Acknowledgements @@ -56,6 +59,7 @@ <boost/endian/conversion.hpp>
+ <boost/endian/buffers.hpp>
<boost/endian/arithmetic.hpp> @@ -64,7 +68,7 @@

Header boost/endian/conversion.hpp provides byte order reversal and conversion functions that convert objects of -the multi-byte built-in +the built-in integer types, and also types float and double, between native, big, or little endian byte ordering. User defined types are also supported.

@@ -76,6 +80,7 @@ elided for compilers that do not support it. Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums.

+Header <boost/endian/conversion.hpp> Synopsis

#define BOOST_ENDIAN_INTRINSIC_MSG "message describing presence or absence of intrinsics"
@@ -92,16 +97,16 @@ namespace endian
   };
 
   // reverse byte order (i.e. endianness)
-  int8_t   reverse_value(int8_t x) noexcept;
-  int16_t  reverse_value(int16_t x) noexcept;
-  int32_t  reverse_value(int32_t x) noexcept;
-  int64_t  reverse_value(int64_t x) noexcept;
-  uint8_t  reverse_value(uint8_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;
+  int8_t   reverse_endianness(int8_t x) noexcept;
+  int16_t  reverse_endianness(int16_t x) noexcept;
+  int32_t  reverse_endianness(int32_t x) noexcept;
+  int64_t  reverse_endianness(int64_t x) noexcept;
+  uint8_t  reverse_endianness(uint8_t x) noexcept;
+  uint16_t reverse_endianness(uint16_t x) noexcept;
+  uint32_t reverse_endianness(uint32_t x) noexcept;
+  uint64_t reverse_endianness(uint64_t x) noexcept;
+  float    reverse_endianness(float x) noexcept;
+  double   reverse_endianness(double x) noexcept;
 
   template <class Value>
   void     reverse(Value& x) noexcept;
@@ -118,30 +123,12 @@ namespace endian
   template <class Reversible>
     void little_endian(Reversible& x) noexcept; 
 
-  // synonyms, based on names popularized by BSD (e.g. OS X, Linux) endian.h
-  //  "h" for "host" (i.e. native), "be" for "big endian",
-  //  "le" for "little endian", "m" for "modify" in place
-  template <class T> T bswap(T x) noexcept      {return reverse_value(x);}
-  template <class T> T htobe(T host) noexcept   {return big_endian_value(host);}
-  template <class T> T htole(T host) noexcept   {return little_endian_value(host);}
-  template <class T> T betoh(T big) noexcept    {return big_endian_value(big);}
-  template <class T> T letoh(T little) noexcept {return little_endian_value(little);}
-
-  template <class T> void bswapm(T& x) noexcept      {reverse(x);}
-  template <class T> void htobem(T& host) noexcept   {big_endian(host);}
-  template <class T> void htole(mT& host noexcept)   {little_endian(host);}
-  template <class T> void betohm(T& big) noexcept    {big_endian(big);}
-  template <class T> void letohm(T& little) noexcept {little_endian(little);}
-
   // generic byte order conversion
   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; 
 
-  // runtime effective byte order determination
-  order effective_order(order x) noexcept;
-
   // runtime byte-order conversion
   template <class ReversibleValue>
     ReversibleValue convert_value(ReversibleValue from,
@@ -152,67 +139,83 @@ namespace endian
 
 } // namespace endian
 } // namespace boost
-

The implementation-defined text above is either -big or little according to the endianness of the -platform.

+

The implementation is required to define the enum class order +constant native as +big on big endian platforms and little on little +endian platforms.

Requirements

-

The template definitions in this header refer to named -requirements whose details are set out in this section. User defined types may -be used in the function templates in this header only if they meet the -function's template parameter requirements.

-

ReversibleValue requirements

-

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

+

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.

- - + + +

reverse_endianness(x)

+ x is a value of a possibly const type convertible + to Reversible. - -
ExpressionReturn typeRequirementMeaning of xRequirements
-

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 type to be -supplied by a C++ program instantiating a template; x is a -modifiable lvalue of type Reversible.

- - - - +

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

+ reverse_endianness_in_place(x) +
ExpressionPost-condition
-

reverse(x)

 + x is a +modifiable lvalue of type Reversible. -

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

See -udt_conversion_example.cpp for an example of a UDT that can used in the -big_endian, -little_endian, and -convert function templates.

+ +
+ +

[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]

+ +
+ +

Customization points for user-defined types (UDTs)

+ +

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

+ +

The endianness conversion function templates that return values are +required to perform reversal of endianness if needed by making an unqualified +call to reverse_endianness(argument), as described in the +preceding table.

+ +

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

+ +

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

+

Functions

-
int8_t  reverse_value(int8_t x) noexcept;
-int16_t  reverse_value(int16_t x) noexcept;
-int32_t  reverse_value(int32_t x) noexcept;
-int64_t  reverse_value(int64_t x) noexcept;
-uint8_t  reverse_value(uint8_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;
+
int8_t  reverse_endianness(int8_t x) noexcept;
+int16_t  reverse_endianness(int16_t x) noexcept;
+int32_t  reverse_endianness(int32_t x) noexcept;
+int64_t  reverse_endianness(int64_t x) noexcept;
+uint8_t  reverse_endianness(uint8_t x) noexcept;
+uint16_t reverse_endianness(uint16_t x) noexcept;
+uint32_t reverse_endianness(uint32_t x) noexcept;
+uint64_t reverse_endianness(uint64_t x) noexcept;
+float    reverse_endianness(float x) noexcept;
+double   reverse_endianness(double x) noexcept;

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

@@ -229,7 +232,7 @@ double reverse_value(double x) noexcept; void big_endian(Reversible& x) noexcept;

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

+ endian, otherwise reverse_endianness(x).

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

Example:

@@ -245,7 +248,7 @@ big_endian(x); // reverses the byte order of x, unless void little_endian(Reversible& x) noexcept;

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

+ endian, otherwise reverse_endianness(x).

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

Example:

@@ -268,7 +271,7 @@ int32_t y(little_endian(x)); 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).

+ reverse_endianness(from).

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

Example:

@@ -278,18 +281,12 @@ int32_t y(little_endian(x)); convert<order::big, order::native>(x); // more generic equivalent of big_endian(x);
-
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>
+
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).

+    order from_order, order to_order) noexcept;

Returns (first form): from if effect_order(from_order) == effective_order(to_order), otherwise reverse_endianness(from).

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

Example:

@@ -304,13 +301,13 @@ convert(x, some_order, order::native); // convert to native byte order if neede

See the Endian home page FAQ for a library-wide FAQ.

-

Why are the template versions of reverse() and reverse_value() +

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

They are unsafe for general use. Consider reversing -the bytes of a std::pair as a whole - the bytes from first +the bytes of a std::pair as a whole - the bytes from first would end up in second and visa versa, and this is totally wrong!

@@ -330,11 +327,11 @@ provided.

Acknowledgements

Tomas Puverle was instrumental in identifying and articulating the need to 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. -Pierre Talbot provided the int8_t reverse_value() and templated +Pierre Talbot provided the int8_t reverse_endianness() and templated reverse() implementations.

Last revised: -19 November, 2014

+07 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/doc/index.html b/doc/index.html index 607947b..d6ebcfe 100644 --- a/doc/index.html +++ b/doc/index.html @@ -58,6 +58,7 @@ <boost/endian/conversion.hpp>
+ <boost/endian/buffers.hpp>
<boost/endian/arithmetic.hpp> @@ -199,8 +200,8 @@ application needs.

These problems are eliminated by defining S like this:

struct S {
-   big_uint16_t a;
-   big_uint32_t b;
+   big_uint16_ut a;
+   big_uint32_ut b;
};

@@ -677,7 +678,7 @@ and 16, 32, and 64-bit aligned integers.

  • order::native is now a synonym for order::big or order::little according to the endianness of the platform, as requested. This reduces the number of template specializations required.
    • -
  • reverse_value() overloads for int8_t and +
  • reverse_endianness() overloads for int8_t and uint8_t have been added for improved generality. (Pierre Talbot)
  • Overloads of reverse() have been replaced with a single reverse() template. (Pierre Talbot)
    • @@ -701,7 +702,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovski,.

    Last revised: -19 November, 2014

    +05 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/doc/mini_review_topics.html b/doc/mini_review_topics.html index e182842..286033b 100644 --- a/doc/mini_review_topics.html +++ b/doc/mini_review_topics.html @@ -71,14 +71,15 @@ the primary use case.

    Support for user defined types (UDTs) is desirable, and should be provided where there would be no conflict with the other concerns.

    -

    Done. Need docs.

    +

    Done. See conversion requirements.

    There is some concern that endian integer/float arithmetic operations might used inadvertently or inappropriately. The impact of adding an endian_buffer class without arithmetic operations should be investigated.

    Done. The endian types have been decomposed into class template - endian_buffer and class template endian_arithmetic. Class + endian_buffer and class template + endian_arithmetic. Class endian_buffer is a public base class for endian_arithmetic, and can also be used by users as a stand-alone class.

    @@ -98,7 +99,7 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff

    Last revised: -27 November, 2014

    +05 December, 2014

    © Copyright Beman Dawes, 2014

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