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

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 actual byte-order determination
  order actual_order(order o) 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

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);

Effects: Reverses the byte order of x.

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);

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

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);

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

Example:

int32_t x = some-value;
native_to_big(x); // converts x to big-endian unless
                  // the native representation is already 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);

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

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

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