third_party/boost/endian/doc/endian/conversion.adoc - platform/external/sdv/vsomeip - Git at Google

 ////
 Copyright 2011-2016 Beman Dawes

 Distributed under the Boost Software License, Version 1.0.
 (http://www.boost.org/LICENSE_1_0.txt)
 ////

 [#conversion]
 # Endian Conversion Functions
 :idprefix: conversion_

 ## Introduction

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

 ## Reference

 Functions are implemented `inline` if appropriate. For {cpp}03 compilers,
 `noexcept` is elided. Boost scoped enum emulation is used so that the library
 still works for compilers that do not support scoped enums.

 ### Definitions

 *Endianness* refers to the ordering of bytes within internal or external
 integers and other arithmetic data. Most-significant byte first is called
 *big endian* ordering. Least-significant byte first is called
 *little endian* ordering. Other orderings are possible and some CPU
 architectures support both big and little ordering.

 NOTE: The names are derived from
 http://en.wikipedia.org/wiki/Jonathan_Swift[Jonathan Swift]'s satirical novel
 _http://en.wikipedia.org/wiki/Gulliver's_Travels[Gulliver's Travels]_, where
 rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an
 extensive description of https://en.wikipedia.org/wiki/Endianness[Endianness].

 The standard integral types ({cpp}std [basic.fundamental]) except `bool` and
 the scoped enumeration types ({cpp}std [dcl.enum]) are collectively called the
 *endian types*. In the absence of padding bits, which is true on the platforms
 supported by the Boost.Endian library, endian types have the property that all
 of their bit patterns are valid values, which means that when an object of an
 endian type has its constituent bytes reversed, the result is another valid value.
 This allows `endian_reverse` to take and return by value.

 Other built-in types, such as `bool`, `float`, or unscoped enumerations, do not
 have the same property, which means that reversing their constituent bytes may
 produce an invalid value, leading to undefined behavior. These types are therefore
 disallowed in `endian_reverse`, but are still allowed in `endian_reverse_inplace`.
 Even if an object becomes invalid as a result of reversing its bytes, as long as
 its value is never read, there would be no undefined behavior.

 ### Header `<boost/endian/conversion.hpp>` Synopsis

 [subs=+quotes]
 ```
 #define BOOST_ENDIAN_INTRINSIC_MSG \
    "`message describing presence or absence of intrinsics`"

 namespace boost
 {
 namespace endian
 {
   enum class order
   {
     native = `see below`,
     big    = `see below`,
     little = `see below`,
   };

   // Byte reversal functions

   template <class Endian>
     Endian endian_reverse(Endian x) noexcept;

   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;

   // In-place byte reversal functions

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

   template<class EndianReversibleInplace, std::size_t N>
     void endian_reverse_inplace(EndianReversibleInplace (&x)[N]) noexcept;

   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;

   // Generic load and store functions

   template<class T, std::size_t N, order Order>
     T endian_load( unsigned char const * p ) noexcept;

   template<class T, std::size_t N, order Order>
     void endian_store( unsigned char * p, T const & v ) noexcept;

   // Convenience load functions

   boost::int16_t load_little_s16( unsigned char const * p ) noexcept;
   boost::uint16_t load_little_u16( unsigned char const * p ) noexcept;
   boost::int16_t load_big_s16( unsigned char const * p ) noexcept;
   boost::uint16_t load_big_u16( unsigned char const * p ) noexcept;

   boost::int32_t load_little_s24( unsigned char const * p ) noexcept;
   boost::uint32_t load_little_u24( unsigned char const * p ) noexcept;
   boost::int32_t load_big_s24( unsigned char const * p ) noexcept;
   boost::uint32_t load_big_u24( unsigned char const * p ) noexcept;

   boost::int32_t load_little_s32( unsigned char const * p ) noexcept;
   boost::uint32_t load_little_u32( unsigned char const * p ) noexcept;
   boost::int32_t load_big_s32( unsigned char const * p ) noexcept;
   boost::uint32_t load_big_u32( unsigned char const * p ) noexcept;

   boost::int64_t load_little_s40( unsigned char const * p ) noexcept;
   boost::uint64_t load_little_u40( unsigned char const * p ) noexcept;
   boost::int64_t load_big_s40( unsigned char const * p ) noexcept;
   boost::uint64_t load_big_u40( unsigned char const * p ) noexcept;

   boost::int64_t load_little_s48( unsigned char const * p ) noexcept;
   boost::uint64_t load_little_u48( unsigned char const * p ) noexcept;
   boost::int64_t load_big_s48( unsigned char const * p ) noexcept;
   boost::uint64_t load_big_u48( unsigned char const * p ) noexcept;

   boost::int64_t load_little_s56( unsigned char const * p ) noexcept;
   boost::uint64_t load_little_u56( unsigned char const * p ) noexcept;
   boost::int64_t load_big_s56( unsigned char const * p ) noexcept;
   boost::uint64_t load_big_u56( unsigned char const * p ) noexcept;

   boost::int64_t load_little_s64( unsigned char const * p ) noexcept;
   boost::uint64_t load_little_u64( unsigned char const * p ) noexcept;
   boost::int64_t load_big_s64( unsigned char const * p ) noexcept;
   boost::uint64_t load_big_u64( unsigned char const * p ) noexcept;

   // Convenience store functions

   void store_little_s16( unsigned char * p, boost::int16_t v ) noexcept;
   void store_little_u16( unsigned char * p, boost::uint16_t v ) noexcept;
   void store_big_s16( unsigned char * p, boost::int16_t v ) noexcept;
   void store_big_u16( unsigned char * p, boost::uint16_t v ) noexcept;

   void store_little_s24( unsigned char * p, boost::int32_t v ) noexcept;
   void store_little_u24( unsigned char * p, boost::uint32_t v ) noexcept;
   void store_big_s24( unsigned char * p, boost::int32_t v ) noexcept;
   void store_big_u24( unsigned char * p, boost::uint32_t v ) noexcept;

   void store_little_s32( unsigned char * p, boost::int32_t v ) noexcept;
   void store_little_u32( unsigned char * p, boost::uint32_t v ) noexcept;
   void store_big_s32( unsigned char * p, boost::int32_t v ) noexcept;
   void store_big_u32( unsigned char * p, boost::uint32_t v ) noexcept;

   void store_little_s40( unsigned char * p, boost::int64_t v ) noexcept;
   void store_little_u40( unsigned char * p, boost::uint64_t v ) noexcept;
   void store_big_s40( unsigned char * p, boost::int64_t v ) noexcept;
   void store_big_u40( unsigned char * p, boost::uint64_t v ) noexcept;

   void store_little_s48( unsigned char * p, boost::int64_t v ) noexcept;
   void store_little_u48( unsigned char * p, boost::uint64_t v ) noexcept;
   void store_big_s48( unsigned char * p, boost::int64_t v ) noexcept;
   void store_big_u48( unsigned char * p, boost::uint64_t v ) noexcept;

   void store_little_s56( unsigned char * p, boost::int64_t v ) noexcept;
   void store_little_u56( unsigned char * p, boost::uint64_t v ) noexcept;
   void store_big_s56( unsigned char * p, boost::int64_t v ) noexcept;
   void store_big_u56( unsigned char * p, boost::uint64_t v ) noexcept;

   void store_little_s64( unsigned char * p, boost::int64_t v ) noexcept;
   void store_little_u64( unsigned char * p, boost::uint64_t v ) noexcept;
   void store_big_s64( unsigned char * p, boost::int64_t v ) noexcept;
   void store_big_u64( unsigned char * p, boost::uint64_t v ) noexcept;

 } // namespace endian
 } // namespace boost
 ```

 The values of `order::little` and `order::big` shall not be equal to one
 another.

 The value of `order::native` shall be:

 * equal to `order::big` if the execution environment is big endian, otherwise
 * equal to `order::little` if the execution environment is little endian,
 otherwise
 * unequal to both `order::little` and `order::big`.

 ### Requirements

 #### 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 {cpp} program instantiating a template; `x` is a value of type (possibly
 `const`) `T`; `mlx` is a modifiable lvalue of type `T`.

 [#conversion_endianreversible]
 ##### EndianReversible requirements (in addition to `CopyConstructible`)

 [%header,cols=3*]
 |===
 |Expression |Return |Requirements
 |`endian_reverse(x)` |`T`
 a|`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 a class type, the function:

 * Is expected to be implemented by the user, as a non-member function in the same
   namespace as `T` that can be found by argument dependent lookup (ADL);
 * Should return 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.
 |===

 [#conversion_endianreversibleinplace]
 ##### EndianReversibleInplace requirements

 [%header,cols=2*]
 |===
 |Expression |Requirements
 |`endian_reverse_inplace(mlx)`
 a|`T` is an integral type, an enumeration type, `float`, `double`, a class type,
 or an array type.

 If `T` is not a class type or an array type, reverses the order of bytes in `mlx`.

 If `T` is a class type, the function:

 * Is expected to be implemented by the user, as a non-member function in the same
   namespace as `T` that can be found by argument dependent lookup (ADL);
 * Should reverse the order of bytes of all data members of `mlx` that have types or
   arrays of types that meet the `EndianReversible` or `EndianReversibleInplace`
   requirements.

 If `T` is an array type, calls `endian_reverse_inplace` on each element.
 |===

 NOTE: Because there is a function template for `endian_reverse_inplace` that
 calls `endian_reverse` for class types, only `endian_reverse` 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 improve efficiency.

 #### Customization points for user-defined types (UDTs)

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

 The library's function templates requiring
 `<<conversion_endianreversible,EndianReversible>>` are required to perform
 reversal of endianness if needed by making an unqualified call to
 `endian_reverse()`.

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

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

 ### Byte Reversal Functions

 ```
 template <class Endian>
 Endian endian_reverse(Endian x) noexcept;
 ```
 [none]
 * {blank}
 +
 Requires:: `Endian` must be a standard integral type that is not `bool`,
   or a scoped enumeration type.
 Returns:: `x`, with the order of its constituent bytes reversed.

 ```
 template <class EndianReversible>
 EndianReversible big_to_native(EndianReversible x) noexcept;
 ```
 [none]
 * {blank}
 +
 Returns:: `conditional_reverse<order::big, order::native>(x)`.

 ```
 template <class EndianReversible>
 EndianReversible native_to_big(EndianReversible x) noexcept;
 ```
 [none]
 * {blank}
 +
 Returns:: `conditional_reverse<order::native, order::big>(x)`.

 ```
 template <class EndianReversible>
 EndianReversible little_to_native(EndianReversible x) noexcept;
 ```
 [none]
 * {blank}
 +
 Returns:: `conditional_reverse<order::little, order::native>(x)`.

 ```
 template <class EndianReversible>
 EndianReversible native_to_little(EndianReversible x) noexcept;
 ```
 [none]
 * {blank}
 +
 Returns:: `conditional_reverse<order::native, order::little>(x)`.

 ```
 template <order O1, order O2, class EndianReversible>
 EndianReversible conditional_reverse(EndianReversible x) noexcept;
 ```
 [none]
 * {blank}
 +
 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 EndianReversible>
 EndianReversible conditional_reverse(EndianReversible x,
      order order1, order order2) noexcept;
 ```
 [none]
 * {blank}
 +
 Returns::
   `order1 == order2? x: endian_reverse(x)`.

 ### In-place Byte Reversal Functions

 ```
 template <class EndianReversible>
 void endian_reverse_inplace(EndianReversible& x) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects:: When `EndianReversible` is a class type,
   `x = endian_reverse(x);`. When `EndianReversible` is an integral
   type, an enumeration type, `float`, or `double`, reverses the
   order of the constituent bytes of `x`. Otherwise, the program is
   ill-formed.

 ```
 template<class EndianReversibleInplace, std::size_t N>
 void endian_reverse_inplace(EndianReversibleInplace (&x)[N]) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects:: Calls `endian_reverse_inplace(x[i])` for `i` from `0` to `N-1`.

 ```
 template <class EndianReversibleInplace>
 void big_to_native_inplace(EndianReversibleInplace& x) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects:: `conditional_reverse_inplace<order::big, order::native>(x)`.

 ```
 template <class EndianReversibleInplace>
 void native_to_big_inplace(EndianReversibleInplace& x) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects:: `conditional_reverse_inplace<order::native, order::big>(x)`.

 ```
 template <class EndianReversibleInplace>
 void little_to_native_inplace(EndianReversibleInplace& x) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects:: `conditional_reverse_inplace<order::little, order::native>(x)`.

 ```
 template <class EndianReversibleInplace>
 void native_to_little_inplace(EndianReversibleInplace& x) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects::  `conditional_reverse_inplace<order::native, order::little>(x)`.

 ```
 template <order O1, order O2, class EndianReversibleInplace>
 void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects:: None if `O1 == O2,` otherwise `endian_reverse_inplace(x)`.
 Remarks:: Which effect applies shall be determined at compile time.

 ```
 template <class EndianReversibleInplace>
 void conditional_reverse_inplace(EndianReversibleInplace& x,
      order order1, order order2) noexcept;
 ```
 [none]
 * {blank}
 +
 Effects::
   If `order1 == order2` then `endian_reverse_inplace(x)`.

 ### Generic Load and Store Functions

 ```
 template<class T, std::size_t N, order Order>
 T endian_load( unsigned char const * p ) noexcept;
 ```
 [none]
 * {blank}
 +
 Requires:: `sizeof(T)` must be 1, 2, 4, or 8. `N` must be between 1 and
   `sizeof(T)`, inclusive. `T` must be trivially copyable. If `N` is not
   equal to `sizeof(T)`, `T` must be integral or `enum`.

 Effects:: Reads `N` bytes starting from `p`, in forward or reverse order
   depending on whether `Order` matches the native endianness or not,
   interprets the resulting bit pattern as a value of type `T`, and returns it.
   If `sizeof(T)` is bigger than `N`, zero-extends when `T` is unsigned,
   sign-extends otherwise.

 ```
 template<class T, std::size_t N, order Order>
 void endian_store( unsigned char * p, T const & v ) noexcept;
 ```
 [none]
 * {blank}
 +
 Requires:: `sizeof(T)` must be 1, 2, 4, or 8. `N` must be between 1 and
   `sizeof(T)`, inclusive. `T` must be trivially copyable. If `N` is not
   equal to `sizeof(T)`, `T` must be integral or `enum`.

 Effects:: Writes to `p` the `N` least significant bytes from the object
   representation of `v`, in forward or reverse order depending on whether
   `Order` matches the native endianness or not.

 ### Convenience Load Functions

 ```
 inline boost::intM_t load_little_sN( unsigned char const * p ) noexcept;
 ```
 [none]
 * {blank}
 +
 Reads an N-bit signed little-endian integer from `p`.
 +
 Returns:: `endian_load<boost::intM_t, N/8, order::little>( p )`.

 ```
 inline boost::uintM_t load_little_uN( unsigned char const * p ) noexcept;
 ```
 [none]
 * {blank}
 +
 Reads an N-bit unsigned little-endian integer from `p`.
 +
 Returns:: `endian_load<boost::uintM_t, N/8, order::little>( p )`.

 ```
 inline boost::intM_t load_big_sN( unsigned char const * p ) noexcept;
 ```
 [none]
 * {blank}
 +
 Reads an N-bit signed big-endian integer from `p`.
 +
 Returns:: `endian_load<boost::intM_t, N/8, order::big>( p )`.

 ```
 inline boost::uintM_t load_big_uN( unsigned char const * p ) noexcept;
 ```
 [none]
 * {blank}
 +
 Reads an N-bit unsigned big-endian integer from `p`.
 +
 Returns::
   `endian_load<boost::uintM_t, N/8, order::big>( p )`.

 ### Convenience Store Functions

 ```
 inline void store_little_sN( unsigned char * p, boost::intM_t v ) noexcept;
 ```
 [none]
 * {blank}
 +
 Writes an N-bit signed little-endian integer to `p`.
 +
 Effects:: `endian_store<boost::intM_t, N/8, order::little>( p, v )`.

 ```
 inline void store_little_uN( unsigned char * p, boost::uintM_t v ) noexcept;
 ```
 [none]
 * {blank}
 +
 Writes an N-bit unsigned little-endian integer to `p`.
 +
 Effects:: `endian_store<boost::uintM_t, N/8, order::little>( p, v )`.

 ```
 inline void store_big_sN( unsigned char * p, boost::intM_t v ) noexcept;
 ```
 [none]
 * {blank}
 +
 Writes an N-bit signed big-endian integer to `p`.
 +
 Effects:: `endian_store<boost::intM_t, N/8, order::big>( p, v )`.

 ```
 inline void store_big_uN( unsigned char * p, boost::uintM_t v ) noexcept;
 ```
 [none]
 * {blank}
 +
 Writes an N-bit unsigned big-endian integer to `p`.
 +
 Effects::
   `endian_store<boost::uintM_t, N/8, order::big>( p, v )`.

 ## FAQ

 See the <<overview_faq,Overview FAQ>> for a library-wide FAQ.

 Why are both value returning and modify-in-place functions provided?::
 Returning the result by value is the standard C and {cpp} 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.

 Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?::
 Those names are non-standard and vary even between POSIX-like operating
 systems. A {cpp} library TS was going to use those names, but found they were
 sometimes implemented as macros. Since macros do not respect scoping and
 namespace rules, to use them would be very error prone.

 ## 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  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 endian_reverse()` and templated `endian_reverse_inplace()`
 implementations.
	////
	Copyright 2011-2016 Beman Dawes

	Distributed under the Boost Software License, Version 1.0.
	(http://www.boost.org/LICENSE_1_0.txt)
	////

	[#conversion]
	# Endian Conversion Functions
	:idprefix: conversion_

	## Introduction

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

	## Reference

	Functions are implemented `inline` if appropriate. For {cpp}03 compilers,
	`noexcept` is elided. Boost scoped enum emulation is used so that the library
	still works for compilers that do not support scoped enums.

	### Definitions

	Endianness refers to the ordering of bytes within internal or external
	integers and other arithmetic data. Most-significant byte first is called
	big endian ordering. Least-significant byte first is called
	little endian ordering. Other orderings are possible and some CPU
	architectures support both big and little ordering.

	NOTE: The names are derived from
	http://en.wikipedia.org/wiki/Jonathan_Swift[Jonathan Swift]'s satirical novel
	_http://en.wikipedia.org/wiki/Gulliver's_Travels[Gulliver's Travels]_, where
	rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an
	extensive description of https://en.wikipedia.org/wiki/Endianness[Endianness].

	The standard integral types ({cpp}std [basic.fundamental]) except `bool` and
	the scoped enumeration types ({cpp}std [dcl.enum]) are collectively called the
	endian types. In the absence of padding bits, which is true on the platforms
	supported by the Boost.Endian library, endian types have the property that all
	of their bit patterns are valid values, which means that when an object of an
	endian type has its constituent bytes reversed, the result is another valid value.
	This allows `endian_reverse` to take and return by value.

	Other built-in types, such as `bool`, `float`, or unscoped enumerations, do not
	have the same property, which means that reversing their constituent bytes may
	produce an invalid value, leading to undefined behavior. These types are therefore
	disallowed in `endian_reverse`, but are still allowed in `endian_reverse_inplace`.
	Even if an object becomes invalid as a result of reversing its bytes, as long as
	its value is never read, there would be no undefined behavior.

	### Header `<boost/endian/conversion.hpp>` Synopsis

	[subs=+quotes]
	```
	#define BOOST_ENDIAN_INTRINSIC_MSG \
	"`message describing presence or absence of intrinsics`"

	namespace boost
	{
	namespace endian
	{
	enum class order
	{
	native = `see below`,
	big = `see below`,
	little = `see below`,
	};

	// Byte reversal functions

	template <class Endian>
	Endian endian_reverse(Endian x) noexcept;

	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;

	// In-place byte reversal functions

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

	template<class EndianReversibleInplace, std::size_t N>
	void endian_reverse_inplace(EndianReversibleInplace (&x)[N]) noexcept;

	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;

	// Generic load and store functions

	template<class T, std::size_t N, order Order>
	T endian_load( unsigned char const * p ) noexcept;

	template<class T, std::size_t N, order Order>
	void endian_store( unsigned char * p, T const & v ) noexcept;

	// Convenience load functions

	boost::int16_t load_little_s16( unsigned char const * p ) noexcept;
	boost::uint16_t load_little_u16( unsigned char const * p ) noexcept;
	boost::int16_t load_big_s16( unsigned char const * p ) noexcept;
	boost::uint16_t load_big_u16( unsigned char const * p ) noexcept;

	boost::int32_t load_little_s24( unsigned char const * p ) noexcept;
	boost::uint32_t load_little_u24( unsigned char const * p ) noexcept;
	boost::int32_t load_big_s24( unsigned char const * p ) noexcept;
	boost::uint32_t load_big_u24( unsigned char const * p ) noexcept;

	boost::int32_t load_little_s32( unsigned char const * p ) noexcept;
	boost::uint32_t load_little_u32( unsigned char const * p ) noexcept;
	boost::int32_t load_big_s32( unsigned char const * p ) noexcept;
	boost::uint32_t load_big_u32( unsigned char const * p ) noexcept;

	boost::int64_t load_little_s40( unsigned char const * p ) noexcept;
	boost::uint64_t load_little_u40( unsigned char const * p ) noexcept;
	boost::int64_t load_big_s40( unsigned char const * p ) noexcept;
	boost::uint64_t load_big_u40( unsigned char const * p ) noexcept;

	boost::int64_t load_little_s48( unsigned char const * p ) noexcept;
	boost::uint64_t load_little_u48( unsigned char const * p ) noexcept;
	boost::int64_t load_big_s48( unsigned char const * p ) noexcept;
	boost::uint64_t load_big_u48( unsigned char const * p ) noexcept;

	boost::int64_t load_little_s56( unsigned char const * p ) noexcept;
	boost::uint64_t load_little_u56( unsigned char const * p ) noexcept;
	boost::int64_t load_big_s56( unsigned char const * p ) noexcept;
	boost::uint64_t load_big_u56( unsigned char const * p ) noexcept;

	boost::int64_t load_little_s64( unsigned char const * p ) noexcept;
	boost::uint64_t load_little_u64( unsigned char const * p ) noexcept;
	boost::int64_t load_big_s64( unsigned char const * p ) noexcept;
	boost::uint64_t load_big_u64( unsigned char const * p ) noexcept;

	// Convenience store functions

	void store_little_s16( unsigned char * p, boost::int16_t v ) noexcept;
	void store_little_u16( unsigned char * p, boost::uint16_t v ) noexcept;
	void store_big_s16( unsigned char * p, boost::int16_t v ) noexcept;
	void store_big_u16( unsigned char * p, boost::uint16_t v ) noexcept;

	void store_little_s24( unsigned char * p, boost::int32_t v ) noexcept;
	void store_little_u24( unsigned char * p, boost::uint32_t v ) noexcept;
	void store_big_s24( unsigned char * p, boost::int32_t v ) noexcept;
	void store_big_u24( unsigned char * p, boost::uint32_t v ) noexcept;

	void store_little_s32( unsigned char * p, boost::int32_t v ) noexcept;
	void store_little_u32( unsigned char * p, boost::uint32_t v ) noexcept;
	void store_big_s32( unsigned char * p, boost::int32_t v ) noexcept;
	void store_big_u32( unsigned char * p, boost::uint32_t v ) noexcept;

	void store_little_s40( unsigned char * p, boost::int64_t v ) noexcept;
	void store_little_u40( unsigned char * p, boost::uint64_t v ) noexcept;
	void store_big_s40( unsigned char * p, boost::int64_t v ) noexcept;
	void store_big_u40( unsigned char * p, boost::uint64_t v ) noexcept;

	void store_little_s48( unsigned char * p, boost::int64_t v ) noexcept;
	void store_little_u48( unsigned char * p, boost::uint64_t v ) noexcept;
	void store_big_s48( unsigned char * p, boost::int64_t v ) noexcept;
	void store_big_u48( unsigned char * p, boost::uint64_t v ) noexcept;

	void store_little_s56( unsigned char * p, boost::int64_t v ) noexcept;
	void store_little_u56( unsigned char * p, boost::uint64_t v ) noexcept;
	void store_big_s56( unsigned char * p, boost::int64_t v ) noexcept;
	void store_big_u56( unsigned char * p, boost::uint64_t v ) noexcept;

	void store_little_s64( unsigned char * p, boost::int64_t v ) noexcept;
	void store_little_u64( unsigned char * p, boost::uint64_t v ) noexcept;
	void store_big_s64( unsigned char * p, boost::int64_t v ) noexcept;
	void store_big_u64( unsigned char * p, boost::uint64_t v ) noexcept;

	} // namespace endian
	} // namespace boost
	```

	The values of `order::little` and `order::big` shall not be equal to one
	another.

	The value of `order::native` shall be:

	* equal to `order::big` if the execution environment is big endian, otherwise
	* equal to `order::little` if the execution environment is little endian,
	otherwise
	* unequal to both `order::little` and `order::big`.

	### Requirements

	#### 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 {cpp} program instantiating a template; `x` is a value of type (possibly
	`const`) `T`; `mlx` is a modifiable lvalue of type `T`.

	[#conversion_endianreversible]
	##### EndianReversible requirements (in addition to `CopyConstructible`)

	[%header,cols=3*]
	\|===
	\|Expression \|Return \|Requirements
	\|`endian_reverse(x)` \|`T`
	a\|`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 a class type, the function:

	* Is expected to be implemented by the user, as a non-member function in the same
	namespace as `T` that can be found by argument dependent lookup (ADL);
	* Should return 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.
	\|===

	[#conversion_endianreversibleinplace]
	##### EndianReversibleInplace requirements

	[%header,cols=2*]
	\|===
	\|Expression \|Requirements
	\|`endian_reverse_inplace(mlx)`
	a\|`T` is an integral type, an enumeration type, `float`, `double`, a class type,
	or an array type.

	If `T` is not a class type or an array type, reverses the order of bytes in `mlx`.

	If `T` is a class type, the function:

	* Is expected to be implemented by the user, as a non-member function in the same
	namespace as `T` that can be found by argument dependent lookup (ADL);
	* Should reverse the order of bytes of all data members of `mlx` that have types or
	arrays of types that meet the `EndianReversible` or `EndianReversibleInplace`
	requirements.

	If `T` is an array type, calls `endian_reverse_inplace` on each element.
	\|===

	NOTE: Because there is a function template for `endian_reverse_inplace` that
	calls `endian_reverse` for class types, only `endian_reverse` 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 improve efficiency.

	#### Customization points for user-defined types (UDTs)

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

	The library's function templates requiring
	`<<conversion_endianreversible,EndianReversible>>` are required to perform
	reversal of endianness if needed by making an unqualified call to
	`endian_reverse()`.

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

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

	### Byte Reversal Functions

	```
	template <class Endian>
	Endian endian_reverse(Endian x) noexcept;
	```
	[none]
	* {blank}
	+
	Requires:: `Endian` must be a standard integral type that is not `bool`,
	or a scoped enumeration type.
	Returns:: `x`, with the order of its constituent bytes reversed.

	```
	template <class EndianReversible>
	EndianReversible big_to_native(EndianReversible x) noexcept;
	```
	[none]
	* {blank}
	+
	Returns:: `conditional_reverse<order::big, order::native>(x)`.

	```
	template <class EndianReversible>
	EndianReversible native_to_big(EndianReversible x) noexcept;
	```
	[none]
	* {blank}
	+
	Returns:: `conditional_reverse<order::native, order::big>(x)`.

	```
	template <class EndianReversible>
	EndianReversible little_to_native(EndianReversible x) noexcept;
	```
	[none]
	* {blank}
	+
	Returns:: `conditional_reverse<order::little, order::native>(x)`.

	```
	template <class EndianReversible>
	EndianReversible native_to_little(EndianReversible x) noexcept;
	```
	[none]
	* {blank}
	+
	Returns:: `conditional_reverse<order::native, order::little>(x)`.

	```
	template <order O1, order O2, class EndianReversible>
	EndianReversible conditional_reverse(EndianReversible x) noexcept;
	```
	[none]
	* {blank}
	+
	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 EndianReversible>
	EndianReversible conditional_reverse(EndianReversible x,
	order order1, order order2) noexcept;
	```
	[none]
	* {blank}
	+
	Returns::
	`order1 == order2? x: endian_reverse(x)`.

	### In-place Byte Reversal Functions

	```
	template <class EndianReversible>
	void endian_reverse_inplace(EndianReversible& x) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: When `EndianReversible` is a class type,
	`x = endian_reverse(x);`. When `EndianReversible` is an integral
	type, an enumeration type, `float`, or `double`, reverses the
	order of the constituent bytes of `x`. Otherwise, the program is
	ill-formed.

	```
	template<class EndianReversibleInplace, std::size_t N>
	void endian_reverse_inplace(EndianReversibleInplace (&x)[N]) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: Calls `endian_reverse_inplace(x[i])` for `i` from `0` to `N-1`.

	```
	template <class EndianReversibleInplace>
	void big_to_native_inplace(EndianReversibleInplace& x) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: `conditional_reverse_inplace<order::big, order::native>(x)`.

	```
	template <class EndianReversibleInplace>
	void native_to_big_inplace(EndianReversibleInplace& x) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: `conditional_reverse_inplace<order::native, order::big>(x)`.

	```
	template <class EndianReversibleInplace>
	void little_to_native_inplace(EndianReversibleInplace& x) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: `conditional_reverse_inplace<order::little, order::native>(x)`.

	```
	template <class EndianReversibleInplace>
	void native_to_little_inplace(EndianReversibleInplace& x) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: `conditional_reverse_inplace<order::native, order::little>(x)`.

	```
	template <order O1, order O2, class EndianReversibleInplace>
	void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept;
	```
	[none]
	* {blank}
	+
	Effects:: None if `O1 == O2,` otherwise `endian_reverse_inplace(x)`.
	Remarks:: Which effect applies shall be determined at compile time.

	```
	template <class EndianReversibleInplace>
	void conditional_reverse_inplace(EndianReversibleInplace& x,
	order order1, order order2) noexcept;
	```
	[none]
	* {blank}
	+
	Effects::
	If `order1 == order2` then `endian_reverse_inplace(x)`.

	### Generic Load and Store Functions

	```
	template<class T, std::size_t N, order Order>
	T endian_load( unsigned char const * p ) noexcept;
	```
	[none]
	* {blank}
	+
	Requires:: `sizeof(T)` must be 1, 2, 4, or 8. `N` must be between 1 and
	`sizeof(T)`, inclusive. `T` must be trivially copyable. If `N` is not
	equal to `sizeof(T)`, `T` must be integral or `enum`.

	Effects:: Reads `N` bytes starting from `p`, in forward or reverse order
	depending on whether `Order` matches the native endianness or not,
	interprets the resulting bit pattern as a value of type `T`, and returns it.
	If `sizeof(T)` is bigger than `N`, zero-extends when `T` is unsigned,
	sign-extends otherwise.

	```
	template<class T, std::size_t N, order Order>
	void endian_store( unsigned char * p, T const & v ) noexcept;
	```
	[none]
	* {blank}
	+
	Requires:: `sizeof(T)` must be 1, 2, 4, or 8. `N` must be between 1 and
	`sizeof(T)`, inclusive. `T` must be trivially copyable. If `N` is not
	equal to `sizeof(T)`, `T` must be integral or `enum`.

	Effects:: Writes to `p` the `N` least significant bytes from the object
	representation of `v`, in forward or reverse order depending on whether
	`Order` matches the native endianness or not.

	### Convenience Load Functions

	```
	inline boost::intM_t load_little_sN( unsigned char const * p ) noexcept;
	```
	[none]
	* {blank}
	+
	Reads an N-bit signed little-endian integer from `p`.
	+
	Returns:: `endian_load<boost::intM_t, N/8, order::little>( p )`.

	```
	inline boost::uintM_t load_little_uN( unsigned char const * p ) noexcept;
	```
	[none]
	* {blank}
	+
	Reads an N-bit unsigned little-endian integer from `p`.
	+
	Returns:: `endian_load<boost::uintM_t, N/8, order::little>( p )`.

	```
	inline boost::intM_t load_big_sN( unsigned char const * p ) noexcept;
	```
	[none]
	* {blank}
	+
	Reads an N-bit signed big-endian integer from `p`.
	+
	Returns:: `endian_load<boost::intM_t, N/8, order::big>( p )`.

	```
	inline boost::uintM_t load_big_uN( unsigned char const * p ) noexcept;
	```
	[none]
	* {blank}
	+
	Reads an N-bit unsigned big-endian integer from `p`.
	+
	Returns::
	`endian_load<boost::uintM_t, N/8, order::big>( p )`.

	### Convenience Store Functions

	```
	inline void store_little_sN( unsigned char * p, boost::intM_t v ) noexcept;
	```
	[none]
	* {blank}
	+
	Writes an N-bit signed little-endian integer to `p`.
	+
	Effects:: `endian_store<boost::intM_t, N/8, order::little>( p, v )`.

	```
	inline void store_little_uN( unsigned char * p, boost::uintM_t v ) noexcept;
	```
	[none]
	* {blank}
	+
	Writes an N-bit unsigned little-endian integer to `p`.
	+
	Effects:: `endian_store<boost::uintM_t, N/8, order::little>( p, v )`.

	```
	inline void store_big_sN( unsigned char * p, boost::intM_t v ) noexcept;
	```
	[none]
	* {blank}
	+
	Writes an N-bit signed big-endian integer to `p`.
	+
	Effects:: `endian_store<boost::intM_t, N/8, order::big>( p, v )`.

	```
	inline void store_big_uN( unsigned char * p, boost::uintM_t v ) noexcept;
	```
	[none]
	* {blank}
	+
	Writes an N-bit unsigned big-endian integer to `p`.
	+
	Effects::
	`endian_store<boost::uintM_t, N/8, order::big>( p, v )`.

	## FAQ

	See the <<overview_faq,Overview FAQ>> for a library-wide FAQ.

	Why are both value returning and modify-in-place functions provided?::
	Returning the result by value is the standard C and {cpp} 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.

	Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?::
	Those names are non-standard and vary even between POSIX-like operating
	systems. A {cpp} library TS was going to use those names, but found they were
	sometimes implemented as macros. Since macros do not respect scoping and
	namespace rules, to use them would be very error prone.

	## 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 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 endian_reverse()` and templated `endian_reverse_inplace()`
	implementations.