#include "comms/field/Optional.h"

Detailed Description

template<typename TField, typename... TOptions>
class comms::field::Optional< TField, TOptions >

Adaptor class to any other field, that makes the field optional.

When field is optional, it may either exist or not. The behaviour of length(), read() and write() operations depends on the current field's mode.

Template Parameters

TField Proper type of the field that needs to be optional.

TOptions

Zero or more options that modify/refine default behaviour of the field.
Supported options are:

Inheritance diagram for comms::field::Optional< TField, TOptions >:

Public Types
using	CommsTag = typename BaseImpl::CommsTag
	Tag indicating type of the field.

using	Endian = typename BaseImpl::Endian
	Endian used for serialisation.

using	Field = TField
	Type of the field.

using	FieldType = typename ParsedOptions::FieldType
	Type of actual extending field specified via comms::option::def::FieldType. More...

using	Mode = OptionalMode
	Mode of the field. More...

using	ParsedOptions = details::OptionsParser< TOptions... >
	All the options provided to this class bundled into struct.

using	ValueType = Field
	Value type of this field, equal to Field.

using	VersionType = typename BaseImpl::VersionType
	Version type.

Public Member Functions
	Optional ()=default
	Default constructor. More...

	Optional (const Field &fieldSrc)
	Construct the field. More...

	Optional (const Optional &)=default
	Copy constructor.

	Optional (Field &&fieldSrc)
	Construct the field. More...

	Optional (Optional &&)=default
	Move constructor.

	~Optional () noexcept=default
	Destructor.

bool	canWrite () const
	Check of whether the field has a consistent value for writing.

bool	doesExist () const
	Check whether mode is equivalent to Mode::Exists. More...

Field &	field ()
	Get an access to the wrapped field object.

const Field &	field () const
	Get an access to the wrapped field object.

Mode	getMode () const
	Get current optional mode.

const ValueType &	getValue () const
	Get value. More...

VersionType	getVersion () const
	Get version of the field. More...

bool	isMissing () const
	Check whether mode is equivalent to Mode::Missing. More...

bool	isTentative () const
	Check whether mode is equivalent to Mode::Tentative. More...

std::size_t	length () const
	Get length required to serialise the current field value. More...

Optional &	operator= (const Optional &)=default
	Copy assignment.

Optional &	operator= (Optional &&)=default
	Move assignment.

template<typename TIter >
ErrorStatus	read (TIter &iter, std::size_t len)
	Read field value from input data sequence. More...

template<typename TIter >
void	readNoStatus (TIter &iter)
	Read field value from input data sequence without error check and status report. More...

bool	refresh ()
	Refresh the field's value. More...

void	setExists ()
	Set mode to Mode::Exists. More...

void	setMissing ()
	Set mode to Mode::Missing. More...

void	setMode (Mode val)
	Get optional mode.

void	setTentative ()
	Set mode to Mode::Tentative. More...

template<typename U >
void	setValue (U &&val)
	Set value. More...

bool	setVersion (VersionType version)
	Default implementation of version update. More...

bool	valid () const
	Check validity of the field value. More...

ValueType &	value ()
	Get an access to the wrapped field object.

const ValueType &	value () const
	Get an access to the wrapped field object.

template<typename TIter >
ErrorStatus	write (TIter &iter, std::size_t len) const
	Write current field value to output data sequence. More...

template<typename TIter >
void	writeNoStatus (TIter &iter) const
	Write current field value to output data sequence without error check and status report. More...

Static Public Member Functions
static constexpr bool	canWrite ()
	Default check of whether the field has a consistent value for writing. More...

static constexpr bool	hasEmptySerialization ()
	Compile time inquiry of whether comms::option::def::EmptySerialization option has been used.

static constexpr bool	hasFailOnInvalid ()
	Compile time inquiry of whether comms::option::def::FailOnInvalid option has been used.

static constexpr bool	hasFieldType ()
	Compile time inquiry of whether comms::option::def::FieldType option has been used.

static constexpr bool	hasIgnoreInvalid ()
	Compile time inquiry of whether comms::option::def::IgnoreInvalid option has been used.

static constexpr bool	hasNonDefaultRefresh ()
	Compile time check if this class has non-default refresh functionality.

static constexpr bool	hasReadNoStatus ()
	Compile time check of whether the field has proper readNoStatus() member function.

static constexpr bool	hasVarLength ()
	Default check of whether the field has variable length definition via comms::option::def::VarLength option. More...

static constexpr bool	hasWriteNoStatus ()
	Compile time check of whether the field has proper writeNoStatus() member function.

static constexpr bool	isVersionDependent ()
	Compile time check if this class is version dependent.

static constexpr std::size_t	maxLength ()
	Get maximal length that is required to serialise field of this type. More...

static constexpr std::size_t	minLength ()
	Get minimal length that is required to serialise field of this type. More...

static constexpr bool	valid ()
	Default validity check. More...

Static Protected Member Functions
template<typename T , typename TIter >
static T	readData (TIter &iter)
	Read data from input buffer. More...

template<typename T , std::size_t TSize, typename TIter >
static T	readData (TIter &iter)
	Read partial data from input buffer. More...

template<typename T , typename TIter >
static void	writeData (T value, TIter &iter)
	Write data into the output buffer. More...

template<std::size_t TSize, typename T , typename TIter >
static void	writeData (T value, TIter &iter)
	Write partial data into the output buffer. More...

Related Functions
(Note that these are not member functions.)
template<typename T >
constexpr bool	isOptional ()
	Compile time check function of whether a provided type is any variant of comms::field::Optional. More...

template<typename TField , typename... TOptions>
bool	operator!= (const Optional< TField, TOptions... > &field1, const Optional< TField, TOptions... > &field2) noexcept
	Non-equality comparison operator. More...

template<typename TField , typename... TOptions>
bool	operator< (const Optional< TField, TOptions... > &field1, const Optional< TField, TOptions... > &field2) noexcept
	Equivalence comparison operator. More...

template<typename TField , typename... TOptions>
bool	operator<= (const Optional< TField, TOptions... > &field1, const Optional< TField, TOptions... > &field2) noexcept
	Equivalence comparison operator. More...

template<typename TField , typename... TOptions>
bool	operator== (const Optional< TField, TOptions... > &field1, const Optional< TField, TOptions... > &field2) noexcept
	Equality comparison operator. More...

template<typename TField , typename... TOptions>
bool	operator> (const Optional< TField, TOptions... > &field1, const Optional< TField, TOptions... > &field2) noexcept
	Equivalence comparison operator. More...

template<typename TField , typename... TOptions>
bool	operator>= (const Optional< TField, TOptions... > &field1, const Optional< TField, TOptions... > &field2) noexcept
	Equivalence comparison operator. More...

template<typename TField , typename... TOptions>
const Optional< TField, TOptions... > &	toFieldBase (const Optional< TField, TOptions... > &field)
	Upcast type of the field definition to its parent comms::field::Optional type in order to have access to its internal types.

template<typename TField , typename... TOptions>
Optional< TField, TOptions... > &	toFieldBase (Optional< TField, TOptions... > &field)
	Upcast type of the field definition to its parent comms::field::Optional type in order to have access to its internal types.

Member Typedef Documentation

◆ FieldType

template<typename TField , typename... TOptions>

using comms::field::Optional< TField, TOptions >::FieldType = typename ParsedOptions::FieldType

Type of actual extending field specified via comms::option::def::FieldType.

void if comms::option::def::FieldType hasn't been applied.

◆ Mode

template<typename TField , typename... TOptions>

using comms::field::Optional< TField, TOptions >::Mode = OptionalMode

Mode of the field.

See also: OptionalMode

Constructor & Destructor Documentation

◆ Optional() [1/3]

template<typename TField , typename... TOptions>

comms::field::Optional< TField, TOptions >::Optional ( )

default

Default constructor.

The mode it is created in is OptionalMode::Tentative.

◆ Optional() [2/3]

template<typename TField , typename... TOptions>

comms::field::Optional< TField, TOptions >::Optional ( const Field & fieldSrc )

explicit

Construct the field.

Parameters

[in] fieldSrc Field to be copied from during construction.

◆ Optional() [3/3]

template<typename TField , typename... TOptions>

comms::field::Optional< TField, TOptions >::Optional ( Field && fieldSrc )

explicit

Construct the field.

Parameters

[in] fieldSrc Field to be moved from during construction.

Member Function Documentation

◆ canWrite()

template<typename... TOptions>

static constexpr bool comms::Field< TOptions >::canWrite ( )

staticconstexprinherited

Default check of whether the field has a consistent value for writing.

Returns: Always true.

◆ doesExist()

template<typename TField , typename... TOptions>

bool comms::field::Optional< TField, TOptions >::doesExist ( ) const

Check whether mode is equivalent to Mode::Exists.

Convenience wrapper for getMode(), equivalent to

return getMode() == Mode::Exists;

comms::field::Optional::getMode

Mode getMode() const

Get current optional mode.

Definition: Optional.h:224

◆ getValue()

template<typename TField , typename... TOptions>

const ValueType& comms::field::Optional< TField, TOptions >::getValue ( ) const

Get value.

Implemented by calling value(), but can be overriden in the derived class

◆ getVersion()

template<typename TField , typename... TOptions>

VersionType comms::field::Optional< TField, TOptions >::getVersion ( ) const

Get version of the field.

Exists only if comms::option::def::VersionStorage option has been provided.

◆ hasVarLength()

template<typename... TOptions>

static constexpr bool comms::Field< TOptions >::hasVarLength ( )

staticconstexprinherited

Default check of whether the field has variable length definition via comms::option::def::VarLength option.

Returns: Always false.

◆ isMissing()

template<typename TField , typename... TOptions>

bool comms::field::Optional< TField, TOptions >::isMissing ( ) const

Check whether mode is equivalent to Mode::Missing.

Convenience wrapper for getMode(), equivalent to

return getMode() == Mode::Missing;

◆ isTentative()

template<typename TField , typename... TOptions>

bool comms::field::Optional< TField, TOptions >::isTentative ( ) const

Check whether mode is equivalent to Mode::Tentative.

Convenience wrapper for getMode(), equivalent to

return getMode() == Mode::Tentative;

◆ length()

template<typename TField , typename... TOptions>

std::size_t comms::field::Optional< TField, TOptions >::length ( ) const

Get length required to serialise the current field value.

Returns: If current mode is OptionalMode::Exists, then the function returns whatever length() member function of the wrapped field returns. Otherwise (for both OptionalMode::Missing and OptionalMode::Tentative) 0 is returned.

◆ maxLength()

template<typename TField , typename... TOptions>

static constexpr std::size_t comms::field::Optional< TField, TOptions >::maxLength ( )

staticconstexpr

Get maximal length that is required to serialise field of this type.

Returns: Same as Field::maxLength()

◆ minLength()

template<typename TField , typename... TOptions>

static constexpr std::size_t comms::field::Optional< TField, TOptions >::minLength ( )

staticconstexpr

Get minimal length that is required to serialise field of this type.

Returns: Same as Field::minLength()

◆ read()

template<typename TField , typename... TOptions>

template<typename TIter >

ErrorStatus comms::field::Optional< TField, TOptions >::read	(	TIter &	iter,
		std::size_t	len
	)

Read field value from input data sequence.

If field is marked as missing (mode is OptionalMode::Missing), function returns comms::ErrorStatus::Success without advancing iterator.
If field is marked as existing (mode is OptionalMode::Exists) the read() member function of the wrapped field object is invoked.
If field is marked to be tentative (mode is OptionalMode::Tentative), the call redirected to wrapped field's read() member function if value of the "len" parameter is greater than 0, i.e. there are still bytes available for reading, and field itself is marked as existing.
Otherwise, field is marked as missing and comms::ErrorStatus::Success is returned.

Parameters

[in,out]	iter	Iterator to read the data.
[in]	len	Number of bytes available for reading.

Returns: Status of read operation.

Postcondition: Iterator is advanced.

◆ readData() [1/2]

template<typename... TOptions>

template<typename T , typename TIter >

static T comms::Field< TOptions >::readData ( TIter & iter )

staticprotectedinherited

Read data from input buffer.

Use this function to read data from the intput buffer maintained by the caller. The endianness of the data will be as specified in options of the class.

Template Parameters

T	Return type
TIter	Type of input iterator

Parameters

[in,out] iter Input iterator.

Returns: The integral type value.

Precondition: TSize <= sizeof(T); The iterator must be valid and can be successfully dereferenced and incremented at least sizeof(T) times.

Postcondition: The iterator is advanced.

Note: Thread safety: Safe for distinct stream buffers, unsafe otherwise.

◆ readData() [2/2]

template<typename... TOptions>

template<typename T , std::size_t TSize, typename TIter >

static T comms::Field< TOptions >::readData ( TIter & iter )

staticprotectedinherited

Read partial data from input buffer.

Use this function to read data from the intput buffer maintained by the caller. The endianness of the data will be as specified in options of the class.

Template Parameters

T	Return type
TSize	number of bytes to read
TIter	Type of input iterator

Parameters

[in,out] iter Input iterator.

Returns: The integral type value.

Precondition: TSize <= sizeof(T); The iterator must be valid and can be successfully dereferenced and incremented at least TSize times.

Postcondition: The internal pointer of the stream buffer is advanced.

Note: Thread safety: Safe for distinct stream buffers, unsafe otherwise.

◆ readNoStatus()

template<typename TField , typename... TOptions>

template<typename TIter >

void comms::field::Optional< TField, TOptions >::readNoStatus ( TIter & iter )

Read field value from input data sequence without error check and status report.

Similar to read(), but doesn't perform any correctness checks and doesn't report any failures.

Parameters

[in,out] iter Iterator to read the data.

Postcondition: Iterator is advanced.

◆ refresh()

template<typename TField , typename... TOptions>

bool comms::field::Optional< TField, TOptions >::refresh ( )

Refresh the field's value.

Will invoke the refresh() member function of the contained field, only if it is marked as "exists", otherwise false will be returned.

Returns: true if the value has been updated, false otherwise

◆ setExists()

template<typename TField , typename... TOptions>

void comms::field::Optional< TField, TOptions >::setExists ( )

Set mode to Mode::Exists.

Convenience wrapper for setMode(), equivalent to

setMode(Mode::Exists);

comms::field::Optional::setMode

void setMode(Mode val)

Get optional mode.

Definition: Optional.h:230

◆ setMissing()

template<typename TField , typename... TOptions>

void comms::field::Optional< TField, TOptions >::setMissing ( )

Set mode to Mode::Missing.

Convenience wrapper for setMode(), equivalent to

setMode(Mode::Missing);

◆ setTentative()

template<typename TField , typename... TOptions>

void comms::field::Optional< TField, TOptions >::setTentative ( )

Set mode to Mode::Tentative.

Convenience wrapper for setMode(), equivalent to

setMode(Mode::Tentative);

◆ setValue()

template<typename TField , typename... TOptions>

template<typename U >

void comms::field::Optional< TField, TOptions >::setValue ( U && val )

Set value.

Implemented as re-assigning to value(), but can be overriden in the derived class.

◆ setVersion()

template<typename TField , typename... TOptions>

bool comms::field::Optional< TField, TOptions >::setVersion ( VersionType version )

Default implementation of version update.

Returns: true in case the field contents have changed, false otherwise

◆ valid() [1/2]

template<typename... TOptions>

static constexpr bool comms::Field< TOptions >::valid ( )

staticconstexprinherited

Default validity check.

Always returns true, can be overriden by the derived class

Returns: Always true

◆ valid() [2/2]

template<typename TField , typename... TOptions>

bool comms::field::Optional< TField, TOptions >::valid ( ) const

Check validity of the field value.

Returns: If field is marked to be missing (mode is OptionalMode::Missing), "true" is returned, otherwise valid() member function of the wrapped field is called.

◆ write()

template<typename TField , typename... TOptions>

template<typename TIter >

ErrorStatus comms::field::Optional< TField, TOptions >::write	(	TIter &	iter,
		std::size_t	len
	)		const

Write current field value to output data sequence.

If field is marked as missing (mode is OptionalMode::Missing) or tentative (mode is OptionalMode::Tentative) the function returns comms::ErrorStatus::Success without advancing iterator.
If field is marked as existing (mode is OptionalMode::Exists) the write() member function of the wrapped field object is invoked.

Parameters

[in,out]	iter	Iterator to write the data.
[in]	len	Maximal number of bytes that can be written.

Returns: Status of write operation.

Postcondition: Iterator is advanced.

◆ writeData() [1/2]

template<typename... TOptions>

template<typename T , typename TIter >

static void comms::Field< TOptions >::writeData	(	T	value,
		TIter &	iter
	)

staticprotectedinherited

Write data into the output buffer.

Use this function to write data to the the buffer maintained by the caller. The endianness of the data will be as specified in the options provided to the class.

Template Parameters

T	Type of the value to write. Must be integral.
Type	of output iterator

Parameters

[in]	value	Integral type value to be written.
[in,out]	iter	Output iterator.

Precondition: The iterator must be valid and can be successfully dereferenced and incremented at least sizeof(T) times.

Postcondition: The iterator is advanced.

Note: Thread safety: Safe for distinct buffers, unsafe otherwise.

◆ writeData() [2/2]

template<typename... TOptions>

template<std::size_t TSize, typename T , typename TIter >

static void comms::Field< TOptions >::writeData	(	T	value,
		TIter &	iter
	)

staticprotectedinherited

Write partial data into the output buffer.

Use this function to write partial data to the buffer maintained by the caller. The endianness of the data will be as specified the class options.

Template Parameters

TSize	Length of the value in bytes known in compile time.
T	Type of the value to write. Must be integral.
TIter	Type of output iterator

Parameters

[in]	value	Integral type value to be written.
[in,out]	iter	Output iterator.

Precondition: TSize <= sizeof(T); The iterator must be valid and can be successfully dereferenced and incremented at least TSize times.

Postcondition: The iterator is advanced.

Note: Thread safety: Safe for distinct buffers, unsafe otherwise.

◆ writeNoStatus()

template<typename TField , typename... TOptions>

template<typename TIter >

void comms::field::Optional< TField, TOptions >::writeNoStatus ( TIter & iter ) const

Write current field value to output data sequence without error check and status report.

Similar to write(), but doesn't perform any correctness checks and doesn't report any failures.

Parameters

[in,out] iter Iterator to write the data.

Postcondition: Iterator is advanced.

Friends And Related Function Documentation

◆ isOptional()

template<typename T >

constexpr bool isOptional ( )

Template Parameters

T Any type.

Returns: true in case provided type is any variant of Optional

◆ operator!=()

template<typename TField , typename... TOptions>

bool operator!=	(	const Optional< TField, TOptions... > &	field1,
		const Optional< TField, TOptions... > &	field2
	)

Parameters

[in]	field1	First field.
[in]	field2	Second field.

Returns: Result of the non-equality comparison of the contained fields.

◆ operator<()

template<typename TField , typename... TOptions>

bool operator<	(	const Optional< TField, TOptions... > &	field1,
		const Optional< TField, TOptions... > &	field2
	)

Parameters

[in]	field1	First field.
[in]	field2	Second field.

Returns: Result of the equivalence comparison of the contained fields.

◆ operator<=()

template<typename TField , typename... TOptions>

bool operator<=	(	const Optional< TField, TOptions... > &	field1,
		const Optional< TField, TOptions... > &	field2
	)

Parameters

[in]	field1	First field.
[in]	field2	Second field.

Returns: Result of the equivalence comparison of the contained fields.

◆ operator==()

template<typename TField , typename... TOptions>

bool operator==	(	const Optional< TField, TOptions... > &	field1,
		const Optional< TField, TOptions... > &	field2
	)

Parameters

[in]	field1	First field.
[in]	field2	Second field.

Returns: Result of the equality comparison of the contained fields.

◆ operator>()

template<typename TField , typename... TOptions>

bool operator>	(	const Optional< TField, TOptions... > &	field1,
		const Optional< TField, TOptions... > &	field2
	)

Parameters

[in]	field1	First field.
[in]	field2	Second field.

Returns: Result of the equivalence comparison of the contained fields.

◆ operator>=()

template<typename TField , typename... TOptions>

bool operator>=	(	const Optional< TField, TOptions... > &	field1,
		const Optional< TField, TOptions... > &	field2
	)

Parameters

[in]	field1	First field.
[in]	field2	Second field.

Returns: Result of the equivalence comparison of the contained fields.

The documentation for this class was generated from the following file:

include/comms/field/Optional.h

Detailed Description

template<typename TField, typename... TOptions> class comms::field::Optional< TField, TOptions >

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Related Functions

Member Typedef Documentation

◆ FieldType

◆ Mode

Constructor & Destructor Documentation

◆ Optional() [1/3]

◆ Optional() [2/3]

◆ Optional() [3/3]

Member Function Documentation

◆ canWrite()

◆ doesExist()

◆ getValue()

◆ getVersion()

◆ hasVarLength()

◆ isMissing()

◆ isTentative()

◆ length()

◆ maxLength()

◆ minLength()

◆ read()

◆ readData() [1/2]

◆ readData() [2/2]

◆ readNoStatus()

◆ refresh()

◆ setExists()

◆ setMissing()

◆ setTentative()

◆ setValue()

◆ setVersion()

◆ valid() [1/2]

◆ valid() [2/2]

◆ write()

◆ writeData() [1/2]

◆ writeData() [2/2]

◆ writeNoStatus()

Friends And Related Function Documentation

◆ isOptional()

◆ operator!=()

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()

template<typename TField, typename... TOptions>
class comms::field::Optional< TField, TOptions >