template<typename TFieldBase, typename... TOptions>
class comms::field::BitmaskValue< TFieldBase, TOptions >
Bitmask value field.
Quite often communication protocols specify bitmask values, where any bit has a specific meaning. Although such masks are can be handled as unsigned integer values using comms::field::IntValue field type, using comms::field::Bitmask may be a bit more convenient.
- Template Parameters
-
TFieldBase | Base class for this field, expected to be a variant of comms::Field. |
TOptions | Zero or more options that modify/refine default behaviour of the field. If no option is provided, the underlying type is assumed to be "unsigned", which is usually 4 bytes long. To redefined the length of the bitmask field, use comms::option::def::FixedLength option. For example:
Base class to all the field classes. Definition: Field.h:33
Enumerator value field. Definition: EnumValue.h:73
The serialised value of the field in the example above will consume sizeof(unsigned) bytes, because the underlying type chosen to be "unsigned" by default. Example below specifies simple bitmask value field with 2 bytes serialisation length: Supported options are:
|
- See also
- COMMS_BITMASK_BITS()
-
COMMS_BITMASK_BITS_ACCESS()
-
COMMS_BITMASK_BITS_ACCESS_NOTEMPLATE()
-
COMMS_BITMASK_BITS_SEQ()
-
COMMS_BITMASK_BITS_SEQ_NOTEMPLATE()
|
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...
|
|
|
(Note that these are not member functions.)
|
#define | COMMS_BITMASK_BITS(...) COMMS_DEFINE_ENUM(BitIdx, __VA_ARGS__) |
| Provide names for bits in comms::field::BitmaskValue field. More...
|
|
#define | COMMS_BITMASK_BITS_ACCESS(...) |
| Generate access functions for bits in comms::field::BitmaskValue field. More...
|
|
#define | COMMS_BITMASK_BITS_ACCESS_NOTEMPLATE(...) COMMS_DO_BIT_ACC_FUNC((*this), __VA_ARGS__) |
| Similar to COMMS_BITMASK_BITS_ACCESS(), but dedicated for non-template classes. More...
|
|
#define | COMMS_BITMASK_BITS_SEQ(...) |
| Combine usage of COMMS_BITMASK_BITS() and COMMS_BITMASK_BITS_ACCESS(). More...
|
|
#define | COMMS_BITMASK_BITS_SEQ_NOTEMPLATE(...) |
| Similar to COMMS_BITMASK_BITS_SEQ(), but dedicated for non-template classes. More...
|
|
template<typename T > |
constexpr bool | isBitmaskValue () |
| Compile time check function of whether a provided type is any variant of comms::field::BitmaskValue. More...
|
|
template<typename TFieldBase , typename... TOptions> |
bool | operator!= (const BitmaskValue< TFieldBase, TOptions... > &field1, const BitmaskValue< TFieldBase, TOptions... > &field2) noexcept |
| Non-equality comparison operator. More...
|
|
template<typename TFieldBase , typename... TOptions> |
bool | operator< (const BitmaskValue< TFieldBase, TOptions... > &field1, const BitmaskValue< TFieldBase, TOptions... > &field2) noexcept |
| Equivalence comparison operator. More...
|
|
template<typename TFieldBase , typename... TOptions> |
bool | operator== (const BitmaskValue< TFieldBase, TOptions... > &field1, const BitmaskValue< TFieldBase, TOptions... > &field2) noexcept |
| Equality comparison operator. More...
|
|
template<typename TFieldBase , typename... TOptions> |
BitmaskValue< TFieldBase, TOptions... > & | toFieldBase (BitmaskValue< TFieldBase, TOptions... > &field) |
| Upcast type of the field definition to its parent comms::field::BitmaskValue type in order to have access to its internal types.
|
|
template<typename TFieldBase , typename... TOptions> |
const BitmaskValue< TFieldBase, TOptions... > & | toFieldBase (const BitmaskValue< TFieldBase, TOptions... > &field) |
| Upcast type of the field definition to its parent comms::field::BitmaskValue type in order to have access to its internal types.
|
|
template<typename... TOptions>
template<typename T , typename TIter >
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.
template<typename... TOptions>
template<typename T , std::size_t TSize, typename TIter >
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.
template<typename TFieldBase , typename... TOptions>
template<typename TIter >
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.
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.
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.
template<typename TFieldBase , typename... TOptions>
template<typename TIter >
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.
template<typename TFieldBase , typename... TOptions>
#define COMMS_BITMASK_BITS |
( |
|
... | ) |
COMMS_DEFINE_ENUM(BitIdx, __VA_ARGS__) |
|
related |
Provide names for bits in comms::field::BitmaskValue field.
Defines BitIdx enum with all the provided values prefixed with "BitIdx_". For example usage of
#define COMMS_BITMASK_BITS(...)
Provide names for bits in comms::field::BitmaskValue field.
Definition: BitmaskValue.h:590
will generate the following enum type:
enum BitIdx
{
BitIdx_first,
BitIdx_second,
BitIdx_third,
BitIdx_fourth,
BitIdx_numOfValues
};
NOTE, that provided names first, second, third, and fourth have found their way to the enum BitIdx.
Also note, that there is automatically added BitIdx_numOfValues value to the end of BitIdx enum.
It is possible to assign values to the provided names. It could be useful when skipping some unused bits. For example
will generate the following enum type:
enum BitIdx
{
BitIdx_first=1,
BitIdx_third=3,
BitIdx_fourth,
BitIdx_numOfValues
};
The macro COMMS_BITMASK_BITS() should be used inside definition of the bitmask field to provide names for the bits for external use:
{
}
Bitmask value field.
Definition: BitmaskValue.h:103
- Note
- Defined in "comms/field/BitmaskValue.h"
template<typename TFieldBase , typename... TOptions>
#define COMMS_BITMASK_BITS_ACCESS |
( |
|
... | ) |
|
|
related |
Value: COMMS_AS_BITMASK_FUNC { \
}\
COMMS_AS_BITMASK_CONST_FUNC { \
} \
COMMS_DO_BIT_ACC_FUNC(asBitmask(), __VA_ARGS__)
Bundle< TFieldBase, TMembers, TOptions... > & toFieldBase(Bundle< TFieldBase, TMembers, TOptions... > &field)
Upcast type of the field definition to its parent comms::field::Bundle type in order to have access t...
Definition: Bundle.h:805
Generate access functions for bits in comms::field::BitmaskValue field.
The COMMS_BITMASK_BITS() macro defines BitIdx enum to be able to access internal bits. However, an ability to provide values to the enumeration values using =val suffixes doesn't allow generation of convenience access functions to the bits. That's why COMMS_BITMASK_BITS_ACCESS() macro was introduced. For every name listed in the parameters list, getBitValue_*() and setBitValue_*() functions will be generated. For example, having the following definition
{
...
}
#define COMMS_BITMASK_BITS_ACCESS(...)
Generate access functions for bits in comms::field::BitmaskValue field.
Definition: BitmaskValue.h:684
is equivalent to having following functions defined:
{
...
bool getBitValue_first() const {
}
void setBitValue_first(
bool value) {
}
bool getBitValue_third() const {
}
void setBitValue_third(
bool value) {
}
bool getBitValue_fourth() const {
}
void setBitValue_fourth(
bool value) {
}
}
bool getBitValue(unsigned bitNum) const
Get bit value.
Definition: BitmaskValue.h:349
void setBitValue(unsigned bitNum, bool val)
Set bit value.
Definition: BitmaskValue.h:356
NOTE, that generated getBitValue_*() and setBitValue_*() functions use BitIdx_* enum values generated by COMMS_BITMASK_BITS(). It means that COMMS_BITMASK_BITS_ACCESS() macro can NOT be used without COMMS_BITMASK_BITS().
- Precondition
- Must be used together with COMMS_BITMASK_BITS()
- Warning
- Some compilers, such as clang or early versions of g++ may have problems compiling code generated by this macro even though it uses valid C++11 constructs in attempt to automatically identify the type of the base class. If the compilation fails, and this macro resides inside a NON-template class, please use COMMS_BITMASK_BITS_ACCESS_NOTEMPLATE() macro instead. In case this macro needs to reside inside a template class, then there is a need to define inner Base type, which specifies exact type of the comms::field::BitmaskValue class. For example:
template <typename... TExtraOptions>
class MyField : public
MyFieldBase,
comms::field::FixedLength<1>,
comms::field::BitmaskReservedBits<0xf2, 0>,
TExtraOptions...
>
{
using Base =
MyFieldBase,
comms::field::FixedLength<1>,
scomms::field::BitmaskReservedBits<0xf2, 0>,
TExtraOptions...
>;
public:
}
- Note
- Defined in "comms/field/BitmaskValue.h"
template<typename TFieldBase , typename... TOptions>
#define COMMS_BITMASK_BITS_ACCESS_NOTEMPLATE |
( |
|
... | ) |
COMMS_DO_BIT_ACC_FUNC((*this), __VA_ARGS__) |
|
related |
Similar to COMMS_BITMASK_BITS_ACCESS(), but dedicated for non-template classes.
The COMMS_BITMASK_BITS_ACCESS() macro is a generic one, which can be used in any class (template, or non-template). However, some compilers (such as g++-4.9 and below, clang-4.0 and below) may fail to compile it even though it uses valid C++11 constructs. If the compilation fails and the class it is being used in is NOT a template one, please use COMMS_BITMASK_BITS_ACCESS_NOTEMPLATE() instead.
template<typename TFieldBase , typename... TOptions>
#define COMMS_BITMASK_BITS_SEQ_NOTEMPLATE |
( |
|
... | ) |
|
|
related |
Value:
COMMS_BITMASK_BITS_ACCESS_NOTEMPLATE(__VA_ARGS__)
Similar to COMMS_BITMASK_BITS_SEQ(), but dedicated for non-template classes.
The COMMS_BITMASK_BITS_SEQ() macro is a generic one, which can be used in any class (template, or non-template). However, some compilers (such as g++-4.9 and below, clang-4.0 and below) may fail to compile it even though it uses valid C++11 constructs. If the compilation fails and the class it is being used in is NOT a template one, please use COMMS_BITMASK_BITS_SEQ_NOTEMPLATE() instead.
- Note
- Defined in "comms/field/BitmaskValue.h"