MicroStrain Serialization [CPP]

(De)serialization in C++. More...

Classes
class	microstrain::SerializerBase
	Represents a view of a buffer of bytes of known capacity. More...
class	microstrain::Serializer< E >
	Serializes or deserializes data to/from a byte buffer. More...

Typedefs
using	microstrain::BigEndianSerializer = Serializer< serialization::Endian::big >
using	microstrain::LittleEndianSerializer = Serializer< serialization::Endian::little >

Functions
template<serialization::Endian E, class T >
std::enable_if< std::is_arithmetic< T >::value, size_t >::type	microstrain::insert (Serializer< E > &buffer, T value)
	Inserts a numeric value to a Serializer. More...
template<serialization::Endian E, class T >
std::enable_if< std::is_arithmetic< T >::value, size_t >::type	microstrain::extract (Serializer< E > &buffer, T &value)
	Reads a numeric value from a Serializer. More...
template<serialization::Endian E, class T , decltype &::insert = nullptr>
std::enable_if< std::is_class< T >::value, size_t >::type	microstrain::insert (microstrain::Serializer< E > &serializer, const T &object)
	Writes a class object to a Serializer. This overload is available to any class which defines a method insert. It shall take a Serializer reference as the sole parameter. More...
template<serialization::Endian E, class T , decltype &::extract = nullptr>
std::enable_if< std::is_class< T >::value, size_t >::type	microstrain::extract (microstrain::Serializer< E > &serializer, T &object)
	Reads a class object from a Serializer. This overload is available to any class which defines a method extract. It shall take a Serializer reference as the sole parameter. More...
template<serialization::Endian E, class T >
size_t	microstrain::insert (Serializer< E > &serializer, const T *values, size_t count)
	Writes an array to a Serializer. More...
template<serialization::Endian E, class T >
size_t	microstrain::extract (Serializer< E > &serializer, T *values, size_t count)
	Reads an array from a Serializer. More...
template<serialization::Endian E, class T >
size_t	microstrain::insert (Serializer< E > &serializer, microstrain::Span< const T > values)
	Writes an array to a Serializer via a Span. More...
template<serialization::Endian E, class T >
size_t	microstrain::extract (Serializer< E > &serializer, microstrain::Span< const T > values)
	Reads an array from a Serializer via a Span. More...
template<serialization::Endian E, class T , size_t N>
size_t	microstrain::insert (Serializer< E > &serializer, const T(&values)[N])
	Writes a fixed-size array to a Serializer. More...
template<serialization::Endian E, class T , size_t N>
size_t	microstrain::extract (Serializer< E > &serializer, T(&values)[N])
	Reads a fixed-size array from a Serializer. More...
template<serialization::Endian E, class T , size_t N>
size_t	microstrain::insert (Serializer< E > &serializer, const std::array< T, N > &values)
	Writes a std::array to a Serializer. More...
template<serialization::Endian E, class T , size_t N>
size_t	microstrain::extract (Serializer< E > &serializer, const std::array< T, N > &values)
	Reads a std::array from a Serializer. More...
template<serialization::Endian E, typename T0 , typename T1 , typename... Ts>
size_t	microstrain::insert (Serializer< E > &serializer, const T0 &value0, const T1 &value1, Ts... values)
	Writes multiple values to a Serializer. More...
template<serialization::Endian E, typename T0 , typename T1 , typename... Ts>
size_t	microstrain::extract (Serializer< E > &serializer, T0 &value0, T1 &value1, Ts &... values)
	Reads multiple values from a Serializer. More...
template<serialization::Endian E, class T >
bool	microstrain::insert (const T &value, uint8_t *buffer, size_t buffer_length, size_t offset=0, bool exact_size=false)
	Serializes a value to a raw byte buffer. More...
template<serialization::Endian E, class T >
bool	microstrain::extract (T &value, const uint8_t *buffer, size_t buffer_length, size_t offset=0, bool exact_size=false)
	Deserializes a value from a raw byte buffer. More...
template<serialization::Endian E, class T >
bool	microstrain::insert (T value, microstrain::Span< uint8_t > buffer, size_t offset=0, bool exact_size=false)
	Serializes a value to a raw byte buffer (span version). More...
template<serialization::Endian E, class T >
bool	microstrain::extract (T &value, microstrain::Span< const uint8_t > buffer, size_t offset=0, bool exact_size=false)
	Deserializes a value from a raw byte buffer (span version). More...
template<typename... Ts>
bool	microstrain::Serializer< E >::insert (const Ts &... values)
	Serializes one or more values. More...
template<typename... Ts>
bool	microstrain::Serializer< E >::extract (Ts &... values)
	Deserializes one or more values. More...
template<class T , class S >
bool	microstrain::Serializer< E >::extract_count (T &count, S max_count)
	Deserializes an integer with maximum permissible value. More...

Detailed Description

(De)serialization in C++.

Typedef Documentation

BigEndianSerializer

using microstrain::BigEndianSerializer = typedef Serializer<serialization::Endian::big>

LittleEndianSerializer

using microstrain::LittleEndianSerializer = typedef Serializer<serialization::Endian::little>

Function Documentation

extract() [1/10]

template<serialization::Endian E, class T , decltype &::extract = nullptr>

std::enable_if<std::is_class<T>::value , size_t>::type microstrain::extract	(	microstrain::Serializer< E > &	serializer,
		T &	object
	)

Reads a class object from a Serializer. This overload is available to any class which defines a method extract. It shall take a Serializer reference as the sole parameter.

Example:

class Foo
{
    int x, y;
    float z;
 
    // E.g. for big endian serialization:
    void extract(microstrain::BigEndianSerializer& serializer) {
        extract(serializer, x, y, z);  // Read x, y, and z parameters.
    }
    // OR, if both big and little serialization are desired:
    template<microstrain::Endian E>
    void insert(microstrain::Serializer<E>& serializer) {
        extract(serializer, x, y, z);  // Read x, y, and z parameters.
    }
};

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of the class. Automatically deduced from the object parameter.

Parameters

serializer	Serializer object pointing to the source buffer.
object	The class to read from the buffer.

Returns

The number of bytes read.

extract() [2/10]

template<serialization::Endian E, class T >

std::enable_if<std::is_arithmetic<T>::value, size_t>::type microstrain::extract	(	Serializer< E > &	buffer,
		T &	value
	)

Reads a numeric value from a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of the value to read. Automatically deduced from the value parameter.

Parameters

	buffer	Serializer object pointing to the source buffer.
[out]	value	The read value is stored in this variable. Can be a reference to bool, int, uint32_t, float, etc.

Returns

The size of T, for consistency.

extract() [3/10]

template<serialization::Endian E, class T , size_t N>

size_t microstrain::extract	(	Serializer< E > &	serializer,
		const std::array< T, N > &	values
	)

Reads a std::array from a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the source buffer.
values	std::array of values

Returns

The total number of bytes read.

extract() [4/10]

template<serialization::Endian E, class T >

size_t microstrain::extract	(	Serializer< E > &	serializer,
		microstrain::Span< const T >	values
	)

Reads an array from a Serializer via a Span.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the source buffer.
values	Span containing pointer and count.

Returns

The total number of bytes read.

extract() [5/10]

template<serialization::Endian E, class T >

size_t microstrain::extract	(	Serializer< E > &	serializer,
		T *	values,
		size_t	count
	)

Reads an array from a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the source buffer.
values	Pointer to the first value in the array.
count	Number of elements in the array to read.

Returns

The total number of bytes read.

extract() [6/10]

template<serialization::Endian E, class T , size_t N>

size_t microstrain::extract	(	Serializer< E > &	serializer,
		T(&)	values[N]
	)

Reads a fixed-size array from a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the source buffer.
values	C-style array of values

Returns

The total number of bytes read.

extract() [7/10]

template<serialization::Endian E, typename T0 , typename T1 , typename... Ts>

size_t microstrain::extract	(	Serializer< E > &	serializer,
		T0 &	value0,
		T1 &	value1,
		Ts &...	values
	)

Reads multiple values from a Serializer.

This function is equivalent to calling extract on each parameter in sequence.

This function can make use of C++17 fold expressions to improve performance by combining the buffer bounds checks when all types are of known size (i.e. numeric types).

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
Ts	Types of values. Automatically deduced from the values parameters.

Parameters

serializer	Serializer object pointing to the destination buffer.
values	One or more parameters to be read.

Returns

The total number of bytes read.

extract() [8/10]

template<serialization::Endian E, class T >

bool microstrain::extract	(	T &	value,
		const uint8_t *	buffer,
		size_t	buffer_length,
		size_t	offset = 0,
		bool	exact_size = false
	)

Deserializes a value from a raw byte buffer.

Use this overload to read a single value without needing to manually construct a Serializer object.

Example:

uint8_t buffer[4] = {0x01, 0x02, 0x03, 0x04};
uint32_t value_BE;
uint32_t value_LE;
extract<microstrain::Endian::big>(value_BE, buffer, sizeof(buffer), 0, true);
extract<microstrain::Endian::little>(value_LE, buffer, sizeof(buffer), 0, true);
// value_BE == 0x01020304
// value_LE == 0x04030201

Template Parameters

E	Endianness of buffer. Must be manually specified.
T	Type of value. Automatically deduced from the value parameter.

Parameters

value	Parameter to deserialize. This can be any serializable type.
buffer	Pointer to first element of the byte buffer.
buffer_length	Length/size of buffer.
offset	Starting offset (default 0).
exact_size	Returns true only if exactly buffer_length-offset bytes are read. Default false.

Returns

False if the buffer doesn't have enough data.

False if exact_size is true and the number of bytes read plus offset didn't equal buffer_length.

True otherwise.

extract() [9/10]

template<serialization::Endian E, class T >

bool microstrain::extract	(	T &	value,
		microstrain::Span< const uint8_t >	buffer,
		size_t	offset = 0,
		bool	exact_size = false
	)

Deserializes a value from a raw byte buffer (span version).

Use this overload to read a single value without needing to manually construct a Serializer object.

Template Parameters

E	Endianness of buffer. Must be manually specified.
T	Type of value. Automatically deduced from the value parameter.

Parameters

value	Parameter to deserialize. This can be any serializable type.
buffer	Source buffer span.
offset	Starting offset (default 0).
exact_size	Returns true only if exactly buffer.size()-offset bytes are read. Default false.

Returns

False if the buffer doesn't have enough data.

False if exact_size is true and the number of bytes read plus offset didn't equal buffer_length.

True otherwise.

extract() [10/10]

template<serialization::Endian E>

template<typename... Ts>

bool microstrain::Serializer< E >::extract

(

Ts &...

values

)

Deserializes one or more values.

This function defers to the non-member function microstrain::extract. By doing so, it allows the user to provide custom overloads for their own types. Any type supported by the non-member functions may be used here.

Template Parameters

Ts	Types of values to deserialize.

Parameters

[out]

values

One or more parameters to deserialize.

Returns

True if all values were successfully read.

extract_count()

template<serialization::Endian E>

template<class T , class S >

bool microstrain::Serializer< E >::extract_count	(	T &	count,
		S	max_count
	)

Deserializes an integer with maximum permissible value.

This function is intended to be used with protocols which have embedded length fields. This function returns false and invalidates the serializer if the count is too large.

Template Parameters

T	Type of value to read. Expected to be integer-like and must support bool operator<=(S).
S	Type of the maximum value. Usually the same integral type as T, but the only requirement is that it can be compared with T.

Parameters

[out]	count	Value read from the buffer. Set to 0 on failure.
	max_count	Maximum permissible value for count (inclusive).

Returns

True if the count was successfully read and is less than or equal to max_count.

insert() [1/10]

template<serialization::Endian E, class T >

bool microstrain::insert	(	const T &	value,
		uint8_t *	buffer,
		size_t	buffer_length,
		size_t	offset = 0,
		bool	exact_size = false
	)

Serializes a value to a raw byte buffer.

Use this overload to write a single value without needing to manually construct a Serializer object.

Example:

uint8_t buffer[256];
uint32_t value = 16909060; // 0x01020304
insert<microstrain::Endian::big>(value, buffer, sizeof(buffer), 0, false);
// Buffer = [0x01, 0x02, 0x03, 0x04]
insert<microstrain::Endian::little>(value, buffer, sizeof(buffer), 0, false);
// Buffer = [0x04, 0x03, 0x02, 0x01]

Template Parameters

E	Endianness of buffer. Must be manually specified.
T	Type of value. Automatically deduced from the value parameter.

Parameters

value	Parameter to serialize. This can be any serializable type.
buffer	Pointer to first element of the byte buffer.
buffer_length	Length/size of buffer.
offset	Starting offset. Default 0.
exact_size	Returns true only if exactly buffer_length plus offset bytes are written. Default false.

Returns

False if the buffer isn't large enough.

False if exact_size is true and the number of bytes written didn't equal buffer_length.

True otherwise.

insert() [2/10]

template<serialization::Endian E>

template<typename... Ts>

bool microstrain::Serializer< E >::insert

(

const Ts &...

values

)

Serializes one or more values.

This function defers to the non-member function microstrain::insert. By doing so, it allows the user to provide custom overloads for their own types. Any type supported by the non-member functions may be used here.

Template Parameters

Ts	Types of values to serialize.

Parameters

values

One or more parameters to serialize.

Returns

True if all values were successfully written.

insert() [3/10]

template<serialization::Endian E, class T , decltype &::insert = nullptr>

std::enable_if<std::is_class<T>::value , size_t>::type microstrain::insert	(	microstrain::Serializer< E > &	serializer,
		const T &	object
	)

Writes a class object to a Serializer. This overload is available to any class which defines a method insert. It shall take a Serializer reference as the sole parameter.

Example:

class Foo
{
    int x, y;
    float z;
 
    // E.g. for big endian serialization:
    void insert(microstrain::BigEndianSerializer& serializer) const {
        insert(serializer, x, y, z);  // Write x, y, and z parameters.
    }
    // OR, if both big and little serialization are desired:
    template<microstrain::Endian E>
    void insert(microstrain::Serializer<E>& serializer) const {
        insert(serializer, x, y, z);  // Write x, y, and z parameters.
    }
};

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of the class. Automatically deduced from the object parameter.

Parameters

serializer	Serializer object pointing to the destination buffer.
object	The class to write to the buffer.

Returns

The number of bytes written.

insert() [4/10]

template<serialization::Endian E, class T >

std::enable_if<std::is_arithmetic<T>::value, size_t>::type microstrain::insert	(	Serializer< E > &	buffer,
		T	value
	)

Inserts a numeric value to a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of the value to write. Automatically deduced from the value parameter.

Parameters

buffer	Serializer object pointing to the destination buffer.
value	A number to write to the buffer. Can be bool, int, uint32_t, float, etc.

Returns

The size of T, for consistency.

insert() [5/10]

template<serialization::Endian E, class T , size_t N>

size_t microstrain::insert	(	Serializer< E > &	serializer,
		const std::array< T, N > &	values
	)

Writes a std::array to a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the destination buffer.
values	std::array of values

Returns

The total number of bytes written.

insert() [6/10]

template<serialization::Endian E, class T >

size_t microstrain::insert	(	Serializer< E > &	serializer,
		const T *	values,
		size_t	count
	)

Writes an array to a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the destination buffer.
values	Pointer to the first value in the array.
count	Number of elements in the array to write.

Returns

The total number of bytes written.

insert() [7/10]

template<serialization::Endian E, class T , size_t N>

size_t microstrain::insert	(	Serializer< E > &	serializer,
		const T(&)	values[N]
	)

Writes a fixed-size array to a Serializer.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the destination buffer.
values	C-style array of values

Returns

The total number of bytes written.

insert() [8/10]

template<serialization::Endian E, typename T0 , typename T1 , typename... Ts>

size_t microstrain::insert	(	Serializer< E > &	serializer,
		const T0 &	value0,
		const T1 &	value1,
		Ts...	values
	)

Writes multiple values to a Serializer.

This function is equivalent to calling insert on each parameter in sequence.

This function can make use of C++17 fold expressions to improve performance by combining the buffer bounds checks when all types are of known size (i.e. numeric types).

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
Ts	Types of values. Automatically deduced from the values parameters.

Parameters

serializer	Serializer object pointing to the destination buffer.
values	One or more parameters to be written.

Returns

The total number of bytes written.

insert() [9/10]

template<serialization::Endian E, class T >

size_t microstrain::insert	(	Serializer< E > &	serializer,
		microstrain::Span< const T >	values
	)

Writes an array to a Serializer via a Span.

Template Parameters

E	Endianness of buffer. Automatically deduced from the serializer parameter.
T	Type of array elements. Automatically deduced from the values parameter.

Parameters

serializer	Serializer object pointing to the destination buffer.
values	Span containing pointer and count.

Returns

The total number of bytes written.

insert() [10/10]

template<serialization::Endian E, class T >

bool microstrain::insert	(	T	value,
		microstrain::Span< uint8_t >	buffer,
		size_t	offset = 0,
		bool	exact_size = false
	)

Serializes a value to a raw byte buffer (span version).

Use this overload to write a single value without needing to manually construct a Serializer object.

Template Parameters

E	Endianness of buffer. Must be manually specified.
T	Type of value. Automatically deduced from the value parameter.

Parameters

value	Parameter to serialize. This can be any serializable type.
buffer	Source buffer span.
offset	Starting offset. Default 0.
exact_size	Returns true only if exactly buffer.size()-offset bytes are written. Default false.

Returns

False if the buffer isn't large enough.

False if exact_size is true and the number of bytes written didn't equal buffer_length.

True otherwise.