duds::general::BitFlags< Tag, BitsType > Class Template Reference

A type-safe bit flag storage class. More...

#include <BitFlags.hpp>

Collaboration diagram for duds::general::BitFlags< Tag, BitsType >:

Public Types
typedef BitsType	bitsType
	The datatype used to store the flags. More...

Public Member Functions
	BitFlags ()=default
	Construct an uninitialized bit flags container. More...
constexpr	BitFlags (const BitsType &b)
	Construct a bit flags container with a specified value. More...
constexpr	BitFlags (const BitFlags &f)
	Construct a bit flags container with a copy of the contents of another container of the same type. More...
BitFlags	clear ()
	Clear all bits. More...
BitFlags	clear (const BitFlags &bf)
	Clear all bits in this object that are set in bf. More...
constexpr BitsType	flags () const
	Returns the value stored in the object. More...
BitFlags	mask (const BitFlags &mask)
	A bit mask operation; bits set in mask will remain unchanged in this object, while all other bits will be cleared. More...
constexpr	operator bool () const
	Evaluate as a boolean. More...
constexpr bool	operator! () const
	Regular logical not. More...
constexpr bool	operator!= (const BitFlags &bf) const
	Regular not equivalent operator. More...
constexpr bool	operator!= (const BitsType &b) const
	Regular not equivalent operator. More...
constexpr BitFlags	operator& (const BitFlags &bf) const
	Regular bitwise and. More...
BitFlags	operator&= (const BitFlags &bf)
	Regular bitwise and assignment. More...
BitFlags	operator= (const BitFlags &bf)
	Regular assignment. More...
constexpr bool	operator== (const BitFlags &bf) const
	Regular equality operator. More...
constexpr bool	operator== (const BitsType &b) const
	Regular equality operator. More...
constexpr BitFlags	operator^ (const BitFlags &bf) const
	Regular bitwise exclusive or. More...
BitFlags	operator^= (const BitFlags &bf)
	Regular bitwise exclusive or assignment. More...
constexpr BitFlags	operator| (const BitFlags &bf) const
	Regular bitwise or. More...
BitFlags	operator|= (const BitFlags &bf)
	Regular bitwise or assignment. More...
constexpr BitFlags	operator~ () const
	Regular bitwise not. More...
BitFlags	set (const BitFlags &bf)
	Set all bits in this object that are set in bf. More...
BitFlags	setMasked (const BitFlags &bf, const BitFlags &mask)
	Changes only the bits in a masked range. More...
BitFlags	setTo (const BitFlags &bf, bool val)
	Make all bits in bf set or clear based on the value of val. More...
constexpr bool	test (const BitFlags &value, const BitFlags &mask) const
	Returns true if the flags identified by mask have the same value as those flags do in value. More...
constexpr bool	test (const BitFlags &valuemask) const
	Returns true if the flags identified by valuemask are all set. More...
BitFlags	toggle (const BitFlags &bf)
	Toggle the bits that are set in bf; all other bits remain unchanged. More...

Static Public Member Functions
static constexpr BitFlags	Bit (BitsType b)
	Makes a bit flags container with a single bit set that is specified by digit number rather than value. More...
static constexpr BitFlags	Zero ()
	Makes a bit flags container with all flags cleared. More...

Private Attributes
BitsType	bits
	The flags. More...

Detailed Description

template<class Tag, class BitsType = int>
class duds::general::BitFlags< Tag, BitsType >

A type-safe bit flag storage class.

This template stores bit flags in a data type upon which regular bitwise operations function, such as integers. The size of the class is the same as the underlying storage type (BitsType). When compiled by gcc using "-O1", using this class with type int generates the same instructions for the same operations as code using an int directly.

This class defines the full set of bitwise operators to work with objects all of this type. The operators intentionally do not work with other types, including BitFlags types with different template parameters. The equality and inequality operators also work when the second operand is a BitsType. Objects of this class can be implicitly converted to BitsType, but may not be assigned a value directly from a BitsType. Bit shift and other arithmetic operators are not defined because they don't make a lot of sense in the context of bit flags.

For each set of interesting bit flags intended for a particular purpose, a typedef should put a name to the template with a unique tag type. The tag type need not have any definition or other mention in the code outside of this typedef.

typedef BitFlags<struct tag_one>  CapabilityFlags;

A particular flag or set of flags can be given a name by defining a constant value:

// a non-member flag
constexpr CapabilityFlags CapabilitySwitch = CapabilityFlags(2);
// a class member flag
class Class {
    public:
    static constexpr CapabilityFlags MemberSwitch = CapabilityFlags(4);
    // equivalent to above
    static constexpr CapabilityFlags MemberSwitch = CapabilityFlags::Bit(2);
};

Flags with multiple bits may also be defined:

constexpr CapabilityFlags CapabilityMask = CapabilityFlags(15);

Flag combinations using already defined constants can also be made:

static constexpr CapabilityFlags CombinedSwitches =
            CapabilitySwitch | Class::MemberSwitch;

Bit flag values with different BitFlags types may not be implicity mixed.

typedef BitFlags<struct tag_two>  OperationFlags;
// compile-time error on the next line
constexpr OperationFlags WontWork = CapabilitySwitch;
// works; it must clearly explicitly be converted
constexpr OperationFlags WillWork = OperationFlags(CapabilitySwitch.flags());

As a general rule, the names used for flag values should be for the true/set state of the flag(s). For instance, "lightOn", or "buttonUp", but not "lightOnOff", or "button". This will make your code more self explanitory.

Template Parameters

Tag	A tag type, normally given as a struct that isn't used elsewhere. This provides type safety; other expansions of this template will not work with each other if they have different tag types, even if the underlying storage type is the same.
BitsType	The underlying storage type. This should normally be an integer that is a fundamental data type. It must be a type that can be set from a constructor declared as constexpr. If signed, the value -1 can be used to check for all bits set. Other than that, signed and unsigned types work the same, although mismatching them will produce warnings with the exception of -1 literals.

Todo:

Write something that is not part of this class that can serialize the flags in a human readable manner with names for the flags that does not impose a particular order on the flags for input.

Write support for stream I/O, or at least stream output, with human readable flags. Even better if it has I18N support, at least for output.

Author

Jeff Jackowski

Definition at line 101 of file BitFlags.hpp.

Member Typedef Documentation

bitsType

template<class Tag, class BitsType = int>

typedef BitsType duds::general::BitFlags< Tag, BitsType >::bitsType

The datatype used to store the flags.

Todo:

I do not like the case of the typedef, but do like the case of the template parameter. Such a bother.

Definition at line 112 of file BitFlags.hpp.

Constructor & Destructor Documentation

BitFlags() [1/3]

template<class Tag, class BitsType = int>

duds::general::BitFlags< Tag, BitsType >::BitFlags ( )

default

Construct an uninitialized bit flags container.

Referenced by duds::general::BitFlags< struct MenuItemFlags >::Bit(), and duds::general::BitFlags< struct MenuItemFlags >::Zero().

BitFlags() [2/3]

template<class Tag, class BitsType = int>

constexpr duds::general::BitFlags< Tag, BitsType >::BitFlags ( const BitsType &  b )

inline

Construct a bit flags container with a specified value.

Parameters

b	The initial value. The type is the storage type BitsType.

Definition at line 121 of file BitFlags.hpp.

BitFlags() [3/3]

template<class Tag, class BitsType = int>

constexpr duds::general::BitFlags< Tag, BitsType >::BitFlags ( const BitFlags< Tag, BitsType > &  f )

inline

Construct a bit flags container with a copy of the contents of another container of the same type.

Parameters

f	The BitFlags object to copy.

Definition at line 127 of file BitFlags.hpp.

Member Function Documentation

Bit()

template<class Tag, class BitsType = int>

static constexpr BitFlags duds::general::BitFlags< Tag, BitsType >::Bit ( BitsType  b )

inlinestatic

Makes a bit flags container with a single bit set that is specified by digit number rather than value.

Parameters

b	The bit number. 0 is the least significant bit.

Definition at line 141 of file BitFlags.hpp.

clear() [1/2]

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::clear ( )

inline

Clear all bits.

Definition at line 245 of file BitFlags.hpp.

Referenced by duds::ui::menu::renderers::BppMenuRenderer::addScrollBar(), duds::hardware::interface::MasterSyncSerial::condStop(), duds::hardware::interface::MasterSyncSerial::converse(), duds::ui::menu::renderers::BppMenuRenderer::disabledIcon(), duds::ui::menu::renderers::BppMenuRenderer::iconDimensions(), duds::ui::menu::renderers::BppMenuRenderer::iconTextMargin(), duds::ui::menu::renderers::BppMenuRenderer::itemMargin(), duds::ui::menu::renderers::BppMenuRenderer::maxVisible(), duds::ui::menu::renderers::BppMenuRenderer::removeScrollBar(), duds::ui::menu::renderers::BppMenuRenderer::render(), duds::hardware::interface::MasterSyncSerial::retire(), duds::ui::menu::renderers::BppMenuRenderer::selectedIcon(), duds::ui::menu::renderers::BppMenuRenderer::stringCache(), duds::ui::menu::renderers::BppMenuRenderer::toggledOffIcon(), duds::ui::menu::renderers::BppMenuRenderer::toggledOnIcon(), duds::ui::menu::renderers::BppMenuRenderer::valueMargin(), and duds::ui::menu::renderers::BppMenuRenderer::valueWidth().

clear() [2/2]

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::clear ( const BitFlags< Tag, BitsType > &  bf )

inline

Clear all bits in this object that are set in bf.

Parameters

bf	The flags to clear.

Definition at line 252 of file BitFlags.hpp.

flags()

template<class Tag, class BitsType = int>

constexpr BitsType duds::general::BitFlags< Tag, BitsType >::flags ( ) const

inline

Returns the value stored in the object.

Definition at line 147 of file BitFlags.hpp.

Referenced by duds::hardware::interface::DigitalPinCap::firstOutputDriveFlag(), std::hash< duds::general::BitFlags< T, B > >::operator()(), duds::hardware::interface::operator<<(), and duds::ui::graphics::PriorityGridLayout::render().

mask()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::mask ( const BitFlags< Tag, BitsType > &  mask )

inline

A bit mask operation; bits set in mask will remain unchanged in this object, while all other bits will be cleared.

Parameters

mask	The mask to apply by a bitwise and operation.

Definition at line 239 of file BitFlags.hpp.

operator bool()

template<class Tag, class BitsType = int>

constexpr duds::general::BitFlags< Tag, BitsType >::operator bool ( ) const

inline

Evaluate as a boolean.

Definition at line 225 of file BitFlags.hpp.

operator!()

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::operator! ( ) const

inline

Regular logical not.

Definition at line 219 of file BitFlags.hpp.

operator!=() [1/2]

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::operator!= ( const BitFlags< Tag, BitsType > &  bf ) const

inline

Regular not equivalent operator.

Definition at line 195 of file BitFlags.hpp.

operator!=() [2/2]

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::operator!= ( const BitsType &  b ) const

inline

Regular not equivalent operator.

Definition at line 207 of file BitFlags.hpp.

operator&()

template<class Tag, class BitsType = int>

constexpr BitFlags duds::general::BitFlags< Tag, BitsType >::operator & ( const BitFlags< Tag, BitsType > &  bf ) const

inline

Regular bitwise and.

Definition at line 165 of file BitFlags.hpp.

operator&=()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::operator &= ( const BitFlags< Tag, BitsType > &  bf )

inline

Regular bitwise and assignment.

Definition at line 171 of file BitFlags.hpp.

operator=()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::operator= ( const BitFlags< Tag, BitsType > &  bf )

inline

Regular assignment.

Definition at line 231 of file BitFlags.hpp.

operator==() [1/2]

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::operator== ( const BitFlags< Tag, BitsType > &  bf ) const

inline

Regular equality operator.

Definition at line 189 of file BitFlags.hpp.

operator==() [2/2]

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::operator== ( const BitsType &  b ) const

inline

Regular equality operator.

Definition at line 201 of file BitFlags.hpp.

operator^()

template<class Tag, class BitsType = int>

constexpr BitFlags duds::general::BitFlags< Tag, BitsType >::operator^ ( const BitFlags< Tag, BitsType > &  bf ) const

inline

Regular bitwise exclusive or.

Definition at line 177 of file BitFlags.hpp.

operator^=()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::operator^= ( const BitFlags< Tag, BitsType > &  bf )

inline

Regular bitwise exclusive or assignment.

Definition at line 183 of file BitFlags.hpp.

operator|()

template<class Tag, class BitsType = int>

constexpr BitFlags duds::general::BitFlags< Tag, BitsType >::operator| ( const BitFlags< Tag, BitsType > &  bf ) const

inline

Regular bitwise or.

Definition at line 153 of file BitFlags.hpp.

operator|=()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::operator|= ( const BitFlags< Tag, BitsType > &  bf )

inline

Regular bitwise or assignment.

Definition at line 159 of file BitFlags.hpp.

operator~()

template<class Tag, class BitsType = int>

constexpr BitFlags duds::general::BitFlags< Tag, BitsType >::operator~ ( ) const

inline

Regular bitwise not.

Definition at line 213 of file BitFlags.hpp.

set()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::set ( const BitFlags< Tag, BitsType > &  bf )

inline

Set all bits in this object that are set in bf.

Parameters

bf	The flags to set.

Definition at line 259 of file BitFlags.hpp.

Referenced by duds::ui::menu::renderers::BppMenuRenderer::recalculateDimensions(), and duds::ui::menu::renderers::BppMenuRenderer::render().

setMasked()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::setMasked ( const BitFlags< Tag, BitsType > &  bf, const BitFlags< Tag, BitsType > &  mask  )

inline

Changes only the bits in a masked range.

Parameters

bf	The new values.
mask	The mask of the bits to change.

Definition at line 278 of file BitFlags.hpp.

Referenced by duds::ui::menu::renderers::BppMenuRenderer::addScrollBar(), duds::ui::graphics::GridLayoutConfig::center(), duds::ui::graphics::GridSizeStep::center(), duds::ui::graphics::GridLayoutConfig::centerHoriz(), duds::ui::graphics::GridSizeStep::centerHoriz(), duds::ui::graphics::GridLayoutConfig::centerVert(), duds::ui::graphics::GridSizeStep::centerVert(), duds::hardware::interface::DigitalPinConfig::combine(), duds::ui::graphics::GridLayoutConfig::justifyDown(), duds::ui::graphics::GridSizeStep::justifyDown(), duds::ui::graphics::GridLayoutConfig::justifyRight(), and duds::ui::graphics::GridSizeStep::justifyRight().

setTo()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::setTo ( const BitFlags< Tag, BitsType > &  bf, bool  val  )

inline

Make all bits in bf set or clear based on the value of val.

Parameters

bf	The flags to change.
val	The value to use for the bit to change.

Definition at line 267 of file BitFlags.hpp.

Referenced by duds::hardware::interface::ConversationPart::bigEndian(), duds::ui::menu::MenuItem::changeEnabledState(), duds::ui::menu::MenuItem::changeToggle(), duds::ui::menu::MenuItem::changeVisibility(), duds::hardware::interface::ConversationPart::extract(), duds::hardware::interface::ConversationPart::littleEndian(), and duds::hardware::interface::linux::GpioDevPort::outputImpl().

test() [1/2]

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::test ( const BitFlags< Tag, BitsType > &  value, const BitFlags< Tag, BitsType > &  mask  ) const

inline

Returns true if the flags identified by mask have the same value as those flags do in value.

Parameters

value	The value to compare against this object.
mask	Identifies the bit flags to test. Flags to test are set.

Definition at line 294 of file BitFlags.hpp.

Referenced by duds::ui::menu::MenuItem::changeToggle(), duds::ui::menu::MenuItem::changeVisibility(), and duds::hardware::interface::DigitalPinCap::compatible().

test() [2/2]

template<class Tag, class BitsType = int>

constexpr bool duds::general::BitFlags< Tag, BitsType >::test ( const BitFlags< Tag, BitsType > &  valuemask ) const

inline

Returns true if the flags identified by valuemask are all set.

Parameters

valuemask

The mask and value to compare against this object.

Definition at line 301 of file BitFlags.hpp.

toggle()

template<class Tag, class BitsType = int>

BitFlags duds::general::BitFlags< Tag, BitsType >::toggle ( const BitFlags< Tag, BitsType > &  bf )

inline

Toggle the bits that are set in bf; all other bits remain unchanged.

Parameters

bf	The flags to toggle.

Definition at line 285 of file BitFlags.hpp.

Referenced by duds::ui::menu::MenuItem::toggle().

Zero()

template<class Tag, class BitsType = int>

static constexpr BitFlags duds::general::BitFlags< Tag, BitsType >::Zero ( )

inlinestatic

Makes a bit flags container with all flags cleared.

Most useful when an implicit type conversion from BitsType to BitFlags is not allowed, but the type needs to be BitFlags.

Definition at line 133 of file BitFlags.hpp.

Member Data Documentation

bits

template<class Tag, class BitsType = int>

BitsType duds::general::BitFlags< Tag, BitsType >::bits

private

The flags.

Definition at line 105 of file BitFlags.hpp.

Referenced by duds::general::BitFlags< struct MenuItemFlags >::clear(), duds::general::BitFlags< struct MenuItemFlags >::flags(), duds::general::BitFlags< struct MenuItemFlags >::mask(), duds::general::BitFlags< struct MenuItemFlags >::operator &(), duds::general::BitFlags< struct MenuItemFlags >::operator &=(), duds::general::BitFlags< struct MenuItemFlags >::operator!(), duds::general::BitFlags< struct MenuItemFlags >::operator!=(), duds::general::BitFlags< struct MenuItemFlags >::operator=(), duds::general::BitFlags< struct MenuItemFlags >::operator==(), duds::general::BitFlags< struct MenuItemFlags >::operator^(), duds::general::BitFlags< struct MenuItemFlags >::operator^=(), duds::general::BitFlags< struct MenuItemFlags >::operator|(), duds::general::BitFlags< struct MenuItemFlags >::operator|=(), duds::general::BitFlags< struct MenuItemFlags >::set(), duds::general::BitFlags< struct MenuItemFlags >::setMasked(), duds::general::BitFlags< struct MenuItemFlags >::setTo(), duds::general::BitFlags< struct MenuItemFlags >::test(), and duds::general::BitFlags< struct MenuItemFlags >::toggle().

---

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

• BitFlags.hpp