fcppt.endianness

Description

Functions to convert and query endianness.

Introduction Example Header files

Introduction

In C++, the representation of objects of fundamental type (like integers) in memory consists of two aspects:

• The object representation which describes the object's size and alignment in bytes.

• The value representation which describes of how many bits an object consists and what their meanings are.

The order of bits can be thought of from left to right, where the most significant bit is the leftmost (meaning it contributes the highest number to the value), and the least significant bit is rightmost (meaning it only contributes 1 to the value).

This order is established by the fact that for unsigned types, left shift (<<) and right shift (>>) are the same as multiplications and divisions with powers of 2.

Such a value representation (consisting of N bits) requires an object representation of M bytes, so that M * bits_in_a_byte is at least N. However, it is not clear to which bytes the individual bits go, not even if they are implemented in the order exposed by the semantics of the shift operations and other bit manipulating operators.

This means that serializing an integer byte by byte and (possibly) reading it back from another machine is not guaranteed to work.

Luckily, there are only two majorly used mappings from bits to bytes, called big and little endianness. For big endianness, the byte containing the most significant bits comes first, where for little endianness the byte containing the least significant bits comes first.

The most used endianness is little, because the x86 and amd64 architectures use it. For example, PowerPC uses big endianness.

Example

To convert endianness, the template function fcppt::endianness::convert can be used. Because endianness conversion is symmetrical, it can not only convert from the host endianness to a given endianness, but it can also convert from a given endianness to the host endianness.

  int const ivariable(108);
 
  // Converts from the host format to little endian, because ivariable is
  // in the host format.
  int const iconverted(fcppt::endianness::convert(ivariable, std::endian::little));
 
  std::cout << "integer, before: " << ivariable << ", integer, after: " << iconverted << '\n';
 
  // Convert the value back to the host format, because iconverted is in
  // little endianness. Should output 108
  std::cout << fcppt::endianness::convert(iconverted, std::endian::little) << '\n';

Header files

Header file	Description
convert.hpp	Contains the fcppt::endianness::convert function
format.hpp	Contains the fcppt::endianness::format enumeration
host_format.hpp	Contains the fcppt::endianness::host_format function
is_big_endian.hpp	Contains the fcppt::endianness::is_big_endian function
is_little_endian.hpp	Contains the fcppt::endianness::is_little_endian function
raw_pointer.hpp	Contains the fcppt::endianness::raw_pointer typedef
raw_value.hpp	Contains the fcppt::endianness::raw_value typedef
reverse_mem.hpp	Contains the fcppt::endianness::reverse_mem function
size_type.hpp	Contains the fcppt::endianness::size_type typedef
swap.hpp	Contains the fcppt::endianness::swap function

Typedefs
using	fcppt::endianness::raw_pointer = fcppt::endianness::raw_value *
	A pointer to raw memory, used to swap bytes.
using	fcppt::endianness::raw_value = unsigned char
	The raw memory type used to swap bytes.
using	fcppt::endianness::size_type = std::size_t
	The size of raw memory, used to swap bytes.

Functions
template<typename Type >
Type	fcppt::endianness::convert (Type const &_value, std::endian const _format)
	Converts the endianness of an object.
FCPPT_DETAIL_SYMBOL void	fcppt::endianness::reverse_mem (fcppt::endianness::raw_pointer data, fcppt::endianness::size_type size)
	Reverses the byte order of a given memory block.
template<typename Type >
Type	fcppt::endianness::swap (Type _value)
	Swaps the endianness of an object.

Typedef Documentation

raw_pointer

using fcppt::endianness::raw_pointer = typedef fcppt::endianness::raw_value *

A pointer to raw memory, used to swap bytes.

raw_value

using fcppt::endianness::raw_value = typedef unsigned char

The raw memory type used to swap bytes.

size_type

using fcppt::endianness::size_type = typedef std::size_t

The size of raw memory, used to swap bytes.

Function Documentation

convert()

template<typename Type >

Type fcppt::endianness::convert	(	Type const &	_value,
		std::endian const	_format
	)

Converts the endianness of an object.

If _format does not match std::endian::native, then _value will have its endianness converted, otherwise it will be returned as-is. This function can be used to convert from the host format to _format, or from _format to the host format.

Template Parameters

Type	Must be an arithmetic type

Parameters

_value	The value to convert
_format	The endianness to convert to

Returns

The converted value

reverse_mem()

FCPPT_DETAIL_SYMBOL void fcppt::endianness::reverse_mem	(	fcppt::endianness::raw_pointer	data,
		fcppt::endianness::size_type	size
	)

Reverses the byte order of a given memory block.

Reverses the byte order of the memory pointed to by data and the size of size.

Parameters

data	The memory to the memory block
size	The size of the memory block

swap()

template<typename Type >

Type fcppt::endianness::swap

(

Type

_value

)

Swaps the endianness of an object.

Swaps the endiannness of _value.

Template Parameters

Type	Must be an arithmetic type

Parameters

_value

The value to swap the endianness for

Returns

The converted value