Endian Conversion Functions

Introduction

Header boost/endian/conversion.hpp 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.

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

namespace boost
{
namespace endian
{
  enum class order {big, little, native};

  // reverse byte order (i.e. endianness)
  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;

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

  // reverse byte order unless native endianness is little
  template <class ReversibleValue >
    ReversibleValue little_endian_value(ReversibleValue x) noexcept; 
  template <class Reversible>
    void little_endian(Reversible& x) noexcept; 

  // synonyms, based on names popularized by BSD (e.g. OS X, Linux)
  //  "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);}

  // compile-time 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,
      order from_order, order to_order) noexcept;
  template <class Reversible>
    void convert(Reversible& x,
      order from_order, order to_order) noexcept;

} // namespace endian
} // namespace boost

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;

Returns: x, with the order of bytes reversed.

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: Reverses the order of bytes in x.

template <class ReversibleValue >
  ReversibleValue big_endian_value(ReversibleValue x) noexcept; 
template <class Reversible>
  void big_endian(Reversible& x) noexcept;

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;
big_endian(x);  // reverses the byte order of x, unless
                // the native byte order is big-endian

template <class ReversibleValue >
  ReversibleValue little_endian_value(ReversibleValue x) noexcept; 
template <class Reversible>
  void little_endian(Reversible& x) noexcept;

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 big-endian value into 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>
  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
© Copyright Beman Dawes, 2011
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt