Endian Conversion Functions

Endian Conversion Functions

Endian Home Conversion Functions Arithmetic Types Buffer Types Choosing Approach

Contents

Introduction
Reference
    Synopsis
    Requirements
      EndianReversible
      Customization for UDTs
Functions
FAQ
Acknowledgements

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 C++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 Jonathan Swift's satirical novel Gulliver’s Travels, where rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an extensive description of Endianness. —end note]

The standard integral types (C++std 3.9.1) except bool are collectively called the endian types.

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

#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,
   };

  int8_t   endian_reverse(int8_t x) noexcept;
  int16_t  endian_reverse(int16_t x) noexcept;
  int32_t  endian_reverse(int32_t x) noexcept;
  int64_t  endian_reverse(int64_t x) noexcept;
  uint8_t  endian_reverse(uint8_t x) noexcept;
  uint16_t endian_reverse(uint16_t x) noexcept;
  uint32_t endian_reverse(uint32_t x) noexcept;
  uint64_t endian_reverse(uint64_t 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;
      
  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;

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

EndianReversible requirements (in addition to CopyConstructible)

Expression Return
type Requirements

endian_reverse(x)

T

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

EndianReversibleInplace requirements (in addition to CopyConstructible)

Expression Requirements

endian_reverse_inplace(mlx)

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. —end note]

Customization points for user-defined types (UDTs)

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

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

The library's function templates requiring 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.

Functions

int8_t   endian_reverse(int8_t x) noexcept;
int16_t  endian_reverse(int16_t x) noexcept;
int32_t  endian_reverse(int32_t x) noexcept;
int64_t  endian_reverse(int64_t x) noexcept;
uint8_t  endian_reverse(uint8_t x) noexcept;
uint16_t endian_reverse(uint16_t x) noexcept;
uint32_t endian_reverse(uint32_t x) noexcept;
uint64_t endian_reverse(uint64_t x) noexcept;

Returns: x, with the order of its constituent bytes reversed.

Remarks: The type of x meets the EndianReversible requirements.

[Note: The Boost.Endian library does not provide overloads for the C++ standard library supplied types. —end note]

template <class EndianReversible>
EndianReversible big_to_native(EndianReversible x) noexcept;

Returns: conditional_reverse<order::big, order::native>(x).

template <class EndianReversible>
EndianReversible native_to_big(EndianReversible x) noexcept;

Returns: conditional_reverse<order::native, order::big>(x).

template <class EndianReversible>
EndianReversible little_to_native(EndianReversible x) noexcept;

Returns: conditional_reverse<order::little, order::native>(x).

template <class EndianReversible>
EndianReversible native_to_little(EndianReversible x) noexcept;

Returns: conditional_reverse<order::native, order::little>(x).

template <order O1, order O2, class EndianReversible>
EndianReversible conditional_reverse(EndianReversible x) noexcept;

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;

Returns: order1 == order2 ? x : endian_reverse(x).

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

Effects: x = endian_reverse(x).

template <class EndianReversibleInplace>
void big_to_native_inplace(EndianReversibleInplace& x) noexcept;

Effects: conditional_reverse_inplace<order::big, order::native>(x).

template <class EndianReversibleInplace>
void native_to_big_inplace(EndianReversibleInplace& x) noexcept;

Effects: conditional_reverse_inplace<order::native, order::big>(x).

template <class EndianReversibleInplace>
void little_to_native_inplace(EndianReversibleInplace& x) noexcept;

Effects: conditional_reverse_inplace<order::little, order::native>(x).

template <class EndianReversibleInplace>
void native_to_little_inplace(EndianReversibleInplace& x) noexcept;

Effects: conditional_reverse_inplace<order::native, order::little>(x).

template <order O1, order O2, class EndianReversibleInplace>
void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept;

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;

Effects: If order1 == order2 then endian_reverse_inplace(x).

FAQ

See the Endian home page 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 C++ 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 are exact-length 8, 16, 32, and 64-bit integers supported rather than the built-in char, short, int, long, long long, etc?

The primary use case, portable file or network data, needs these de facto standard sizes. Using types that vary with the platform would greatly limit portability for both programs and data.

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 C++ 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.

Last revised: 14 October, 2015

Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt

Header <boost/endian/conversion.hpp> Synopsis

Customization points for user-defined types (UDTs)

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