A class containing a set of flags. More...
#include <BitMask.h>
Public Types | |
| using | Mask_t = BitMask< Storage > |
| This type. More... | |
| using | FlagIndex_t = util::flags::Index_t |
| Type of index of flag. More... | |
| using | Bits_t = util::flags::Bits_t< Storage_t > |
| Set of bits. More... | |
| using | Flag_t = typename Bits_t::Flag_t |
| Type identifying a single flag. More... | |
Exceptions | |
| using | Exception = errors::Exception |
| Generic BitMask exception. More... | |
| using | OutOfRangeError = errors::OutOfRange |
| Out-of-range flag index. More... | |
| using | FlagNotDefinedError = errors::FlagNotDefined |
| Flag not defined. More... | |
Public Member Functions | |
| constexpr bool | operator== (Mask_t const &other) const |
| constexpr bool | operator!= (Mask_t const &other) const |
| template<typename Stream > | |
| void | dump (Stream &&out, unsigned int nBits) const |
| Prints into the specified stream the least nBits significant bits. More... | |
| template<typename Stream > | |
| void | dump (Stream &&out) const |
| Prints into the specified stream all bits. More... | |
Constructors from values | |
These constructors initialize the bit mask from the traditional bit mask constants in C style. The first argument of them should be | |
| constexpr | BitMask ()=default |
| Default constructor: no flag defined at all. More... | |
| constexpr | BitMask (BitMaskFromValuesTag, Storage_t defined) |
| Constructor: defines and sets flags. More... | |
| constexpr | BitMask (BitMaskFromValuesTag, Storage_t defined, Storage_t values) |
| Constructor: defines and sets flags. More... | |
| constexpr | BitMask (BitMaskFromValuesTag, Bits_t values) |
| Constructor: defines and sets flags. More... | |
| constexpr | BitMask (BitMaskFromValuesTag, Bits_t defined, Bits_t values) |
| Constructor: defines and sets flags. More... | |
Constructors combining flags | |
| template<typename... Others> | |
| constexpr | BitMask (Flag_t first, Others...others) |
| Constructor: merges all arguments in the argument list. More... | |
| template<typename... Others> | |
| constexpr | BitMask (Bits_t first, Others...others) |
| Constructor: merges all arguments in the argument list. More... | |
| template<typename Second , typename... Others> | |
| constexpr | BitMask (Mask_t first, Second second, Others...others) |
| Constructor: merges all arguments in the argument list. More... | |
Access to flags | |
| constexpr bool | isDefined (Flag_t flag) const |
| Returns whether the flag is defined. More... | |
| constexpr bool | isDefined (Bits_t bits) const |
| Returns whether all specified bits are defined. More... | |
| constexpr bool | isUndefined (Flag_t flag) const |
| Returns whether the flag is undefined. More... | |
| constexpr bool | isUndefined (Bits_t bits) const |
| Returns whether all specified bits are undefined. More... | |
| constexpr bool | get (Flag_t flag) const |
| Returns if the specified flag is on ("set"). More... | |
| constexpr bool | isSet (Flag_t flag) const |
| Returns if the specified flag is set. More... | |
| constexpr bool | isUnset (Flag_t flag) const |
| Returns if the specified flag is unset. More... | |
| constexpr bool | all (Bits_t bits) const |
| Returns whether all the specified bits are set. More... | |
| constexpr bool | any (Bits_t bits) const |
| Returns whether at least one of the specified bits is set. More... | |
| constexpr bool | none (Bits_t bits) const |
| Returns whether all the specified bits are unset. More... | |
| constexpr bool | anySet (Mask_t const &mask) const |
| Returns whether any of the bits set in the mask are set. More... | |
| constexpr bool | noneSet (Mask_t const &mask) const |
| Returns whether none of the bits set in the mask is set. More... | |
| constexpr bool | match (Mask_t const &mask) const |
| Returns whether all bits defined in the mask are equal to ours. More... | |
Setting flags | |
| template<typename Flag , typename... OtherFlags> | |
| void | set (Flag first, OtherFlags...others) |
| Sets all specified flags. More... | |
| template<typename BeginIter , typename EndIter > | |
| void | rangeSet (BeginIter begin, EndIter end) |
| Sets all flags specified by the index iterator range. More... | |
| template<typename Flag , typename... OtherFlags> | |
| void | unset (Flag first, OtherFlags...others) |
| Unsets all specified flags. More... | |
| template<typename BeginIter , typename EndIter > | |
| void | rangeUnset (BeginIter begin, EndIter end) |
| Unsets all flags specified by the index iterator range. More... | |
| template<typename Flag , typename... OtherFlags> | |
| void | remove (Flag first, OtherFlags...others) |
| Declares all specified flags as undefined. More... | |
| void | clear () |
| Undefines all bits. More... | |
Static Public Member Functions | |
Number of flags | |
| static constexpr size_t | capacity () |
| Returns the number of flags the set has room for. More... | |
Static mask manipulation | |
| template<typename... Args> | |
| static constexpr Mask_t | create (Args...args) |
| Creates a new BitMask. More... | |
| static constexpr Mask_t | mergeIntoMask (Mask_t baseMask, Mask_t mask) |
Returns a new mask with the content of the other mask merged. More... | |
| static constexpr Mask_t | mergeIntoMask (Mask_t baseMask, Bits_t bits) |
| Returns a new mask with the specified bits defined and set. More... | |
| static constexpr Mask_t | mergeIntoMask (Mask_t baseMask, Flag_t flag) |
| Returns a new mask with the specified flag defined and set. More... | |
| static constexpr Mask_t | combineWithMask (Mask_t A, Mask_t B) |
| Returns a new mask combining bits set from two masks. More... | |
| static constexpr Mask_t | combineWithMask (Mask_t baseMask, Bits_t bits) |
| Returns a new mask with the specified flag defined and set. More... | |
| static constexpr Mask_t | combineWithMask (Mask_t baseMask, Flag_t flag) |
| Returns a new mask with the specified flag defined and set. More... | |
| static constexpr Mask_t | intersectWithMask (Mask_t A, Mask_t B) |
| Returns a new mask with the bits set from both masks. More... | |
| static constexpr Mask_t | intersectWithMask (Mask_t baseMask, Bits_t bits) |
| Returns a new mask with only the specified bits set. More... | |
| static constexpr Mask_t | intersectWithMask (Mask_t baseMask, Flag_t flag) |
| Returns a new mask with the specified flag as only set flag. More... | |
| static constexpr Mask_t | unsetMask (Mask_t baseMask, Mask_t mask) |
| Returns a new mask with the bits set from both masks. More... | |
| static constexpr Mask_t | unsetMask (Mask_t baseMask, Bits_t bits) |
| Returns a new mask with only the specified bits set. More... | |
| static constexpr Mask_t | unsetMask (Mask_t baseMask, Flag_t flag) |
| Returns a new mask with the specified flag as only set flag. More... | |
| static constexpr Mask_t | negateMask (Mask_t mask) |
| Returns the negation of mask. More... | |
| static constexpr Mask_t | negateMask (Bits_t bits) |
| Returns a new mask with the specified bits unset. More... | |
| static constexpr Mask_t | negateMask (Flag_t flag) |
| Returns a new mask with the specified flag unset. More... | |
Static Public Attributes | |
| static constexpr auto | fromValues = maskFromValues |
| Constructor tag from values. More... | |
Private Types | |
| using | Storage_t = Storage |
| Type of underlying bit data representation. More... | |
Private Member Functions | |
| void | defineSingle (Flag_t flag) |
| Marks a flag as defined. Value is still uninitialised! More... | |
| void | undefineSingle (Flag_t flag) |
| Marks a flag as undefined. More... | |
| void | undefineImpl () |
| Implementation detail of remove() More... | |
| template<typename... Flags> | |
| void | undefineImpl (Flag_t flag, Flags...others) |
| Implementation detail of remove() More... | |
| void | setImpl () |
| Implementation detail of set() More... | |
| template<typename... Flags> | |
| void | setImpl (Flag_t flag, Flags...others) |
| Implementation detail of set() More... | |
| void | setSingle (Flag_t flag) |
| Implementation detail of set() More... | |
| void | unsetImpl () |
| Implementation detail of unset() More... | |
| constexpr Bits_t | definedOnly () const |
| Returns a bit set with all undefined bits unset. More... | |
| template<typename... Flags> | |
| void | unsetImpl (Flag_t flag, Flags...others) |
| Implementation detail of unset() More... | |
| void | unsetSingle (Flag_t flag) |
| Implementation detail of unset() More... | |
Static Private Member Functions | |
| static constexpr bool | testBits (Storage_t data, Storage_t bits) |
| Returns whether any of the specified bits is set. More... | |
| static constexpr bool | testBitmask (Storage_t data, Storage_t mask) |
| Returns whether all the specified bits in the mask are set. More... | |
| static constexpr bool | testUnsetBitmask (Storage_t data, Storage_t mask) |
| Returns whether all the specified bits in the mask are set. More... | |
Private Attributes | |
| Bits_t | values |
| Storage of value bits. More... | |
| Bits_t | presence |
| Storage of definition bits. More... | |
A class containing a set of flags.
| NFlags | number of flags to be allocated |
| Storage | underlying integral type whose bits represent the flags |
A BitMask contains a set of flags. Each flag can be in one of two states ("set" and "unset"), or can be not defined at all ("undefined").
Note that the object might have a capacity() larger than just NFlags. The flags after the first NFlags are "unsupported", in the sense that in future implementations they might disappear. For the rest, they behave just like the other flags though.
| using util::flags::BitMask< Storage >::Bits_t = util::flags::Bits_t<Storage_t> |
| using util::flags::BitMask< Storage >::Exception = errors::Exception |
| using util::flags::BitMask< Storage >::Flag_t = typename Bits_t::Flag_t |
| using util::flags::BitMask< Storage >::FlagIndex_t = util::flags::Index_t |
| using util::flags::BitMask< Storage >::FlagNotDefinedError = errors::FlagNotDefined |
| using util::flags::BitMask< Storage >::Mask_t = BitMask<Storage> |
| using util::flags::BitMask< Storage >::OutOfRangeError = errors::OutOfRange |
|
private |
|
explicitdefault |
Default constructor: no flag defined at all.
| constexpr util::flags::BitMask< Storage >::BitMask | ( | BitMaskFromValuesTag | , |
| Storage_t | defined | ||
| ) |
Constructor: defines and sets flags.
| defined | a bit mask of the values to be defined and set |
All bits in values will be defined and set. Example:
| constexpr util::flags::BitMask< Storage >::BitMask | ( | BitMaskFromValuesTag | , |
| Storage_t | defined, | ||
| Storage_t | values | ||
| ) |
Constructor: defines and sets flags.
| defined | a bit mask of the flags to be defined |
| values | a bit mask of the values to be set |
If a bit value is requested to be set (in values), it will be also defined, regardless whether its definition bit (in defined) is set. Example:
| constexpr util::flags::BitMask< Storage >::BitMask | ( | BitMaskFromValuesTag | , |
| Bits_t | values | ||
| ) |
Constructor: defines and sets flags.
| values | a bit mask of the values to be set |
| constexpr util::flags::BitMask< Storage >::BitMask | ( | BitMaskFromValuesTag | , |
| Bits_t | defined, | ||
| Bits_t | values | ||
| ) |
Constructor: defines and sets flags.
| defined | a bit mask of the flags to be defined |
| values | a bit mask of the values to be set |
If a bit value is requested to be set (in values), it will be also defined, regardless whether its definition bit (in defined) is set.
|
inline |
Constructor: merges all arguments in the argument list.
| Others | type of the remaining parameters to be merged |
| first | first argument to be merged (here, a Flag_t) |
| others | remaining arguments to be merged |
The effect is equivalent to call create(first, others...).
Definition at line 536 of file BitMask.h.
|
inline |
Constructor: merges all arguments in the argument list.
| Others | type of the remaining parameters to be merged |
| first | first argument to be merged (here, a Bits_t) |
| others | remaining arguments to be merged |
The effect is equivalent to call create(first, others...).
Definition at line 550 of file BitMask.h.
|
inline |
Constructor: merges all arguments in the argument list.
| Second | type of the second argument to be merged |
| Others | type of the remaining arguments to be merged |
| first | first argument to be merged (here, a Mask_t) |
| second | second argument to be merged |
| others | remaining arguments to be merged |
The effect is equivalent to call create(first, others...).
Definition at line 569 of file BitMask.h.
| constexpr bool util::flags::BitMask< Storage >::all | ( | Bits_t | bits | ) | const |
Returns whether all the specified bits are set.
| bits | bits to check |
This method is equivalent to calling isSet(Flag_t) on each single flag defined in bits. The result is true only if all of them are set, that includes all of them being defined.
| constexpr bool util::flags::BitMask< Storage >::any | ( | Bits_t | bits | ) | const |
Returns whether at least one of the specified bits is set.
| bits | bits to check |
isSet(Flag_t)This method is equivalent to calling isSet(Flag_t) on each single flag defined in bits. The result is true only if at least one of them is set (including that one being defined).
| constexpr bool util::flags::BitMask< Storage >::anySet | ( | Mask_t const & | mask | ) | const |
|
static |
Returns the number of flags the set has room for.
|
inline |
|
static |
Returns a new mask combining bits set from two masks.
The content of the new mask has a bit set if it was set (isSet()) in either of the masks, otherwise unset if it was unset (isUnset()) in either of the masks, or else undefined (isUndefined()), as it was undefined in both masks.
The result differs from mergeIntoMask() only for bits which are set (isSet()) in the first mask but unset (isUnset()) in the second: combineWithMask() will leave the bit set, like in the first mask, while mergeIntoMask() would have that bit always unset.
This is equivalent to a flagwise OR operation.
The truth table of the operation is described in the following table, where '-' represents an undefined flag (isUndefined()), '0' an unset flag (isUnset()), and '1' a set flag (isSet()).
| B | - | 0 | 1 |
|---|---|---|---|
| A | |||
| - | - | 0 | 1 |
| 0 | 0 | 0 | 1 |
| 1 | 1 | 1 | 1 |
|
static |
Returns a new mask with the specified flag defined and set.
| baseMask | the starting mask |
| bits | the bits to be set |
The truth table of this operation follows (see mergeIntoMask() for its legend).
bits | 0 | 1 |
|---|---|---|
baseMask | ||
| - | - | 1 |
| 0 | 0 | 1 |
| 1 | 1 | 1 |
|
static |
Returns a new mask with the specified flag defined and set.
| baseMask | the starting mask |
| flag | the single flag to be set |
|
static |
Creates a new BitMask.
| Args | types of the arguments |
| args | the data to create the mask from |
If no argument is provided, the mask is returned with all the flags undefined (like in default constructor). The order of the arguments matters: the first arguments are processed first and their effect can be overridden by the following arguments. For the details, see mergeIntoMask(), which is used to incrementally merge the argument to create the result.
|
private |
Returns a bit set with all undefined bits unset.
|
private |
Marks a flag as defined. Value is still uninitialised!
| void util::flags::BitMask< Storage >::dump | ( | Stream && | out, |
| unsigned int | nBits | ||
| ) | const |
Prints into the specified stream the least nBits significant bits.
|
inline |
| constexpr bool util::flags::BitMask< Storage >::get | ( | Flag_t | flag | ) | const |
Returns if the specified flag is on ("set").
| flag | index of the flag to test |
This method provides an unchecked access to a single flag value. If the flag is isUndefined(), the behaviour of this method is also undefined.
|
static |
Returns a new mask with the bits set from both masks.
The content of the new mask has a bit set if it was set (isSet()) in both masks, otherwise unset if it was unset (isUnset()) in either of the masks, or else undefined (isUndefined()), as it was undefined in both masks.
This is equivalent to a flagwise AND operation.
The truth table of the operation is described in the following table, where '-' represents an undefined flag (isUndefined()), '0' an unset flag (isUnset()), and '1' a set flag (isSet()).
B | - | 0 | 1 |
|---|---|---|---|
A | |||
| - | - | 0 | 1 |
| 0 | 0 | 0 | 0 |
| 1 | 1 | 0 | 1 |
|
static |
Returns a new mask with only the specified bits set.
| baseMask | the starting mask |
| bits | the bits to be set |
All bits in the argument are also defined.
The truth table of this operation follows (see mergeIntoMask() for its legend).
bits | 0 | 1 |
|---|---|---|
baseMask | ||
| - | - | 1 |
| 0 | 0 | 0 |
| 1 | 0 | 1 |
|
static |
Returns a new mask with the specified flag as only set flag.
| baseMask | the starting mask |
| flag | the single flag to be set |
| constexpr bool util::flags::BitMask< Storage >::isDefined | ( | Flag_t | flag | ) | const |
Returns whether the flag is defined.
| flag | index of the flag to check |
A flag must be defined before it can be used. A common convention is to use the "undefined" state of the flag to denote that its value is currently unknown.
A flag is defined by setting (set()) or unsetting (unset()) it.
| constexpr bool util::flags::BitMask< Storage >::isDefined | ( | Bits_t | bits | ) | const |
Returns whether all specified bits are defined.
| bits | bits to check |
This method is equivalent to calling isDefined(Flag_t) on each single flag defined in bits. The result is true only if all of them are defined.
| constexpr bool util::flags::BitMask< Storage >::isSet | ( | Flag_t | flag | ) | const |
Returns if the specified flag is set.
| flag | index of the flag to test |
This method provides an unchecked access to a single flag value. If the flag is isUndefined(), the behaviour of this method is also undefined.
| constexpr bool util::flags::BitMask< Storage >::isUndefined | ( | Flag_t | flag | ) | const |
Returns whether the flag is undefined.
| flag | index of the flag to check |
This is exactly the negation of isDefined().
| constexpr bool util::flags::BitMask< Storage >::isUndefined | ( | Bits_t | bits | ) | const |
Returns whether all specified bits are undefined.
| bits | bits to check |
This is exactly the negation of isDefined().
| constexpr bool util::flags::BitMask< Storage >::isUnset | ( | Flag_t | flag | ) | const |
Returns if the specified flag is unset.
| flag | index of the flag to test |
This method provides an unchecked access to a single flag value. If the flag is isUndefined(), the behaviour of this method is also undefined.
| constexpr bool util::flags::BitMask< Storage >::match | ( | Mask_t const & | mask | ) | const |
Returns whether all bits defined in the mask are equal to ours.
| mask | the mask of bits |
The flags that are undefined in mask are not used to compute the result. If all the flags that are set in mask (isSet()) are set in this object, and likewise all the flags that are unset in mask (isUnset()) are unset, this method returns true.
|
static |
Returns a new mask with the content of the other mask merged.
| baseMask | the starting mask |
| mask | the bits to be set |
The content of the new mask overrides the base one: if a flag is defined in mask, it is defined and copied into the result, otherwise the state of the flag is copied from baseMask.
The truth table of the operation is described in the following table, where '-' represents an undefined flag (isUndefined()), '0' an unset flag (isUnset()), and '1' a set flag (isSet()).
mask | - | 0 | 1 |
|---|---|---|---|
baseMask | |||
| - | - | 0 | 1 |
| 0 | 0 | 0 | 1 |
| 1 | 1 | 0 | 1 |
|
static |
Returns a new mask with the specified bits defined and set.
| baseMask | the starting mask |
| bits | the bits to be set |
The truth table of this operation follows (see mergeIntoMask() for its legend).
bits | 0 | 1 |
|---|---|---|
baseMask | ||
| - | - | 1 |
| 0 | 0 | 1 |
| 1 | 1 | 1 |
|
static |
Returns a new mask with the specified flag defined and set.
| baseMask | the starting mask |
| flag | the single flag to be set |
|
static |
Returns the negation of mask.
| mask | the starting mask |
The bits which were undefined, stay so. The others change their value.
The truth table of this operation follows (see mergeIntoMask() for its legend).
mask | negate() |
|---|---|
| - | - |
| 0 | 1 |
| 1 | 0 |
|
static |
Returns a new mask with the specified bits unset.
| bits | bits to be unset |
Only the unset bits are defined.
|
static |
Returns a new mask with the specified flag unset.
| flag | the single flag to be set |
| constexpr bool util::flags::BitMask< Storage >::none | ( | Bits_t | bits | ) | const |
Returns whether all the specified bits are unset.
| bits | bits to check |
isUnset(Flag_t)This method is equivalent to calling isUnset(Flag_t) on each single flag defined in bits. The result is true only if all of them are unset, that includes all of them being defined.
| constexpr bool util::flags::BitMask< Storage >::noneSet | ( | Mask_t const & | mask | ) | const |
|
inline |
Comparison: not all flags must be the same
Definition at line 845 of file BitMask.h.
|
inline |
Comparison: all flags must be the same
Definition at line 840 of file BitMask.h.
| void util::flags::BitMask< Storage >::rangeSet | ( | BeginIter | begin, |
| EndIter | end | ||
| ) |
Sets all flags specified by the index iterator range.
| BeginIter | type of iterator to the first of the flags |
| EndIter | type of end iterator |
| begin | iterator to the index of the first flag |
| end | iterator past the index of the last flag |
Each flag is set as if set(flag) were called.
| void util::flags::BitMask< Storage >::rangeUnset | ( | BeginIter | begin, |
| EndIter | end | ||
| ) |
Unsets all flags specified by the index iterator range.
| BeginIter | type of iterator to the first of the flags |
| EndIter | type of end iterator |
| begin | iterator to the index of the first flag |
| end | iterator past the index of the last flag |
Each flag is unset as if unset(flag) were called.
|
inline |
Declares all specified flags as undefined.
| Flag | types of the first flag |
| OtherFlags | types of other optional flags |
| first | the first flag to be removed |
| others | flags also to be removed |
All specified flags are marked back as undefined. Already undefined flags are not affected. The value of an undefined flag is... well, undefined.
There is no equivalent direct way to just define a flag, but rather when a flag is assigned a value the first time, that flag is at the same time defined.
Each argument can be of one of the following supported types:
Flag_t: single flag (a FlagIndex_t can be implicitly converted to this one, too) Definition at line 817 of file BitMask.h.
|
inline |
Sets all specified flags.
| Flag | types of the first flag |
| OtherFlags | types of other optional flags |
| first | the first flag to be set |
| others | flags also to be set |
All specified flags are set. Flags set are automatically defined.
Each argument can be of one of the following supported types:
Flag_t: single flag (a FlagIndex_t can be implicitly converted to this one, too) Definition at line 751 of file BitMask.h.
|
inlineprivate |
|
private |
Implementation detail of set()
|
private |
Implementation detail of set()
|
inlinestaticprivate |
|
inlinestaticprivate |
|
inlinestaticprivate |
|
inlineprivate |
|
private |
Implementation detail of remove()
|
private |
Marks a flag as undefined.
|
inline |
Unsets all specified flags.
| Flag | types of the first flag |
| OtherFlags | types of other optional flags |
| first | the first flag to be unset |
| others | flags also to be unset |
All specified flags are unset. Flags unset are automatically defined. The types accepted are the same as for set().
Definition at line 779 of file BitMask.h.
|
inlineprivate |
|
private |
Implementation detail of unset()
|
static |
Returns a new mask with the bits set from both masks.
| baseMask | one of the masks to be combined |
| mask | the other mask to be combined |
The content of the new mask has a bit set if it was set (isSet()) in both masks, otherwise unset if it was unset (isUnset()) in either of the masks, or else undefined (isUndefined()), as it was undefined in both masks.
The truth table of this operation follows (see mergeIntoMask() for its legend).
mask | - | 0 | 1 |
|---|---|---|---|
baseMask | |||
| - | - | 0 | 0 |
| 0 | 0 | 0 | 0 |
| 1 | 1 | 1 | 0 |
|
static |
Returns a new mask with only the specified bits set.
| baseMask | the starting mask |
| bits | the bits to be set |
All bits in the argument are also defined.
The truth table of this operation follows (see mergeIntoMask() for its legend).
bits | 0 | 1 |
|---|---|---|
baseMask | ||
| - | - | 0 |
| 0 | 0 | 0 |
| 1 | 1 | 0 |
|
static |
Returns a new mask with the specified flag as only set flag.
| baseMask | the starting mask |
| flag | the single flag to be set |
|
private |
Implementation detail of unset()
|
static |
|
private |
|
private |
1.8.11