doc/endian/conversion.adoc

////
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 3.9.1) except `bool` are collectively
called the *endian types*.

### 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>
    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:

* 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).
|===

[#conversion_endianreversibleinplace]
##### EndianReversibleInplace requirements (in addition to `CopyConstructible`)

[%header,cols=2*]
|===
|Expression |Requirements
|`endian_reverse_inplace(mlx)`
a|`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 a 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: 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 `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`.
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:: `x = endian_reverse(x)`.

```
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.