boost.png (6897 bytes) Endian Conversion Functions
Boost Home     Endian Home     Conversion Functions     Integer Types     Tutorial
Contents
Introduction
Reference
    Synopsis
    Members
Acknowledgements
Headers
<boost/endian/conversion.hpp>
<boost/endian/integers.hpp>

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)
  //
  inline int16_t  reverse_value(int16_t x) noexcept;
  inline int32_t  reverse_value(int32_t x) noexcept;
  inline int64_t  reverse_value(int64_t x) noexcept;
  inline uint16_t reverse_value(uint16_t x) noexcept;
  inline uint32_t reverse_value(uint32_t x) noexcept;
  inline uint64_t reverse_value(uint64_t x) noexcept;
  inline float    reverse_value(float x) noexcept;
  inline double   reverse_value(double x) noexcept; 

  // reverse bytes unless native endianness is big
  //
  template <class ReversibleValue >
  inline ReversibleValue big_endian_value(ReversibleValue x) noexcept; 

  // reverse bytes unless native endianness is little
  //
  template <class ReversibleValue >
  inline ReversibleValue little_endian_value(ReversibleValue x) noexcept; 

  // synonyms, based on names popularized by BSD (e.g. OS X, Linux)
  // "h" stands for "host" (i.e. native), "be" for "big endian", "le" for "little endian"
  //
  template <class T> T bswap(T x)      {return reverse_value(x);}
  template <class T> T htobe(T host)   {return big_endian_value(host);}
  template <class T> T htole(T host)   {return little_endian_value(host);}
  template <class T> T betoh(T big)    {return big_endian_value(big);}
  template <class T> T letoh(T little) {return little_endian_value(little);}

  // compile-time generic byte order conversion
  template <order From, order To, class ReversibleValue>
    ReversibleValue convert_value(ReversibleValue from) 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;

//--------------------------------------------------------------------------------------//
// modify in place interface //
//--------------------------------------------------------------------------------------//

// reverse byte order (i.e. endianness)
// 
inline void reverse(int16_t& x) noexcept;
inline void reverse(int32_t& x) noexcept;
inline void reverse(int64_t& x) noexcept;
inline void reverse(uint16_t& x) noexcept;
inline void reverse(uint32_t& x) noexcept;
inline void reverse(uint64_t& x) noexcept;
inline void reverse(float& x) noexcept;
inline void reverse(double& x) noexcept; 

// reverse unless native endianness is big
template <class Reversible>
inline void big_endian(Reversible& x) noexcept; 
// Effects: none if native endian order is big, otherwise reverse(x)

// reverse unless native endianness is little
template <class Reversible>
inline void little_endian(Reversible& x) noexcept; 
// Effects: none if native endian order is little, otherwise reverse(x);

// synonyms based on names popularized by BSD, e.g. OS X, Linux.
// "h" stands for "host" (i.e. native), "be" for "big endian",
// "le" for "little endian", "m" for "modify in place"
template <class T> void mbswap(T& x) {reverse(x);}
template <class T> void mhtobe(T& host_) {big_endian(host_);}
template <class T> void mhtole(T& host_) {little_endian(host_);}
template <class T> void mbetoh(T& big_endian_) {big_endian(big_endian_);}
template <class T> void mletoh(T& little_endian_) {little_endian(little_endian_);}

// compile-time generic byte order conversion
template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible>
void convert(Reversible& x) noexcept; 

// runtime byte-order conversion
template <class Reversible>
void convert(Reversible& x, BOOST_SCOPED_ENUM(order) from_order,
BOOST_SCOPED_ENUM(order) to_order) noexcept;

} // namespace endian
} // namespace boost

Members

inline void reorder(int16_t& x);
inline void reorder(int32_t& x);
inline void reorder(int64_t& x);
inline void reorder(uint16_t& x);
inline void reorder(uint32_t& x);
inline void reorder(uint64_t& x);

Effects: Reverses the byte order of x.

inline void reorder(int16_t source, int16_t& target);
inline void reorder(int32_t source, int32_t& target);
inline void reorder(int64_t source, int64_t& target);
inline void reorder(uint16_t source, uint16_t& target);
inline void reorder(uint32_t source, uint32_t& target);
inline 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