Endian conversion

Overview

Utilities for handling byte order.

Functions
template<typename T >
constexpr T	pw::bytes::ConvertOrder (endian from, endian to, T value)
template<typename T >
constexpr T	pw::bytes::ConvertOrderTo (endian to_endianness, T value)
template<typename T >
constexpr T	pw::bytes::ConvertOrderFrom (endian from_endianness, T value)
	Converts a value from the specified byte order to the native byte order.
template<typename T , typename U >
constexpr void	pw::bytes::CopyInOrder (endian order, T value, U *dest)
template<typename T >
constexpr auto	pw::bytes::CopyInOrder (endian order, T value)
	Copies the provided value to a std::array with the specified endianness.
template<typename T >
T	pw::bytes::ReadInOrder (endian order, const void *buffer)
template<typename T >
T	pw::bytes::ReadInOrder (endian order, const void *buffer, size_t max_bytes_to_read)
template<typename T , typename B , size_t kBufferSize, typename = std::enable_if_t<kBufferSize != dynamic_extent && sizeof(B) == sizeof(std::byte)>>
T	pw::bytes::ReadInOrder (endian order, span< B, kBufferSize > buffer)
	Reads a value from a static-extent span, with compile-time bounds checking.
template<typename T , typename B , size_t kBufferSize>
T	pw::bytes::ReadInOrder (endian order, const std::array< B, kBufferSize > &buffer)
	Reads a value from a std::array, with compile-time bounds checking.
template<typename T , typename B , size_t kBufferSize>
T	pw::bytes::ReadInOrder (endian order, const B(&buffer)[kBufferSize])
	Reads a value from a C array, with compile-time bounds checking.
template<typename T >
bool	pw::bytes::ReadInOrder (endian order, ConstByteSpan buffer, T &value)

Function Documentation

ConvertOrder()

template<typename T >

constexpr T pw::bytes::ConvertOrder ( endian  from, endian  to, T  value  )

constexpr

Reorders the bytes in the provided integral value to match the specified byte order. This is similar to the htonl() family of functions.

If the value is converted to non-system endianness, it must NOT be used directly, since the value will be meaningless. Such values are only suitable to memcpy'd or sent to a different device.

ConvertOrderTo()

template<typename T >

constexpr T pw::bytes::ConvertOrderTo ( endian  to_endianness, T  value  )

constexpr

Converts a value from native byte order to the specified byte order. Since this function changes the value's endianness, the result should only be used to memcpy the bytes to a buffer or send to a different device.

CopyInOrder()

template<typename T , typename U >

constexpr void pw::bytes::CopyInOrder ( endian  order, T  value, U *  dest  )

constexpr

Copies the provided value to a buffer with the specified endianness.

Warning

The buffer MUST be at least sizeof(T) bytes large!

ReadInOrder() [1/3]

template<typename T >

T pw::bytes::ReadInOrder	(	endian	order,
		const void *	buffer
	)

Reads a value from a buffer with the specified endianness.

Warning

The buffer MUST be at least sizeof(T) bytes large! If you are not absolutely certain the input buffer is large enough, use the ReadInOrder overload that returns a bool, which checks the buffer size at runtime.

ReadInOrder() [2/3]

template<typename T >

T pw::bytes::ReadInOrder	(	endian	order,
		const void *	buffer,
		size_t	max_bytes_to_read
	)

Reads up to the smaller of max_bytes_to_read and sizeof(T) bytes from a buffer with the specified endianness.

The value is zero-initialized. If max_bytes_to_read is smaller than sizeof(T), the upper bytes of the value are 0.

Warning

The buffer MUST be at least as large as the smaller of max_bytes_to_read and sizeof(T)!

ReadInOrder() [3/3]

template<typename T >

bool pw::bytes::ReadInOrder	(	endian	order,
		ConstByteSpan	buffer,
		T &	value
	)

Reads a value with the specified endianness from the buffer, with runtime bounds checking.

Returns

true if successful, false if buffer is too small for a T.