3.0.0
Freundlich's C++ toolkit
Typedefs | Enumerations | Functions
fcppt.endianness

Description

Functions to convert and query endianness.

Introduction

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

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.

fcppt provides simple means to query the endianness of the machine and to convert endianness of objects of fundamental types.

Example

To query the endianness of the host, the functions fcppt::endianness::host_format can be used. There are also shorthand functions called fcppt::endianness::is_little_endian and fcppt::endianness::is_big_endian.

switch(
)
{
std::cout << "This system is big endian\n";
break;
std::cout << "This system is little endian\n";
break;
}

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(
ivariable,
)
);
<< "integer, before: "
<< ivariable
<< ", integer, after: "
<< iconverted
<< '\n';
// Convert the value back to the host format, because iconverted is in
// little endianness. Should output 108
iconverted,
)
<< '\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

typedef fcppt::endianness::raw_valuefcppt::endianness::raw_pointer
 A pointer to raw memory, used to swap bytes. More...
 
typedef unsigned char fcppt::endianness::raw_value
 The raw memory type used to swap bytes. More...
 
typedef std::size_t fcppt::endianness::size_type
 The size of raw memory, used to swap bytes. More...
 

Enumerations

enum  fcppt::endianness::format { fcppt::endianness::format::little, fcppt::endianness::format::big }
 An enumeration for the possible endiannesses. More...
 

Functions

template<typename Type >
Type fcppt::endianness::convert (Type const &_value, fcppt::endianness::format const _format)
 Converts the endianness of an object. More...
 
FCPPT_DETAIL_SYMBOL fcppt::endianness::format fcppt::endianness::host_format ()
 Returns the endianness of this machine. More...
 
FCPPT_DETAIL_SYMBOL bool fcppt::endianness::is_big_endian ()
 Returns if this machine uses big endianness. More...
 
FCPPT_DETAIL_SYMBOL bool fcppt::endianness::is_little_endian ()
 Returns if this machine uses little endianness. More...
 
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. More...
 
template<typename Type >
Type fcppt::endianness::swap (Type _value)
 Swaps the endianness of an object. More...
 

Typedef Documentation

◆ raw_pointer

A pointer to raw memory, used to swap bytes.

◆ raw_value

typedef unsigned char fcppt::endianness::raw_value

The raw memory type used to swap bytes.

◆ size_type

typedef std::size_t fcppt::endianness::size_type

The size of raw memory, used to swap bytes.

Enumeration Type Documentation

◆ format

An enumeration for the possible endiannesses.

Enumerator
little 

Little endianness.

This means that the least significant bits are in the first byte. It is also the most common endianness, because x86 and amd64 architectures use it.

big 

Big endianness.

This means that the most significant bits are in the first byte.

Function Documentation

◆ convert()

template<typename Type >
Type fcppt::endianness::convert ( Type const &  _value,
fcppt::endianness::format const  _format 
)

Converts the endianness of an object.

If _format does not match the fcppt::endianness::host_format, 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
TypeMust be an arithmetic type
Parameters
_valueThe value to convert
_formatThe endianness to convert to
Returns
The converted value

◆ host_format()

FCPPT_DETAIL_SYMBOL fcppt::endianness::format fcppt::endianness::host_format ( )

Returns the endianness of this machine.

◆ is_big_endian()

FCPPT_DETAIL_SYMBOL bool fcppt::endianness::is_big_endian ( )

Returns if this machine uses big endianness.

Equivalent to host_format() == format::big

◆ is_little_endian()

FCPPT_DETAIL_SYMBOL bool fcppt::endianness::is_little_endian ( )

Returns if this machine uses little endianness.

Equivalent to host_format() == format::little

◆ 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
dataThe memory to the memory block
sizeThe 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
TypeMust be an arithmetic type
Parameters
_valueThe value to swap the endianness for
Returns
The converted value