2.10.0
Freundlich's C++ toolkit
Classes | Typedefs | Functions
fcppt.container.bitfield

Description

A statically sized bitfield.

Motivation

Consider the states "a person can be hungry and tired, not hungry and tired, hungry and not tired or not hungry and not tired". Being hungry and being tired are orthogonal states which can be implemented using the bit representation of an enumeration:

enum person_status
{
hungry = 1,
tired = 1 << 1,
// insert more options here
};

This has a multitude of problems: It abuses enums, it is tiresome to write and it is limited by the number of bits the biggest integer type can hold. To fix this, a bitfield is indexed by natural numbers instead of powers of two and can hold an arbitrary (but fixed) number of bits.

Requirements

fcppt::container::bitfield::object<ElementType, NumElements, InternalType> has the following requirements:

Example

Bitfields are mostly used with enums, see fcppt.enum and fcppt::container::bitfield::enum_object.

Here's a small example:

namespace
{
enum class person_status
{
hungry,
tired,
fcppt_maximum = tired // note the extra field here
};
typedef
person_status
>
bitfield;
void
bitfield const &_field
)
{
<< FCPPT_TEXT("Person status: hungry: ")
<< (_field & person_status::hungry)
<< FCPPT_TEXT('\n')
<< FCPPT_TEXT("Person status: tired: ")
<< (_field & person_status::tired)
<< FCPPT_TEXT('\n');
}
}
int main()
{
// Initialize the bitfield to all zeros
bitfield field(
);
output(field);
// Set a flag, the bitwise kind of way
field |= person_status::hungry;
output(field);
// And unset it again
field &= ~bitfield{person_status::hungry};
// You can access a single flag via operator[]
<< FCPPT_TEXT("person is hungry: ")
<< field[person_status::hungry]
<< FCPPT_TEXT('\n');
// You can also set a flag this way:
field[person_status::hungry] = false;
<< FCPPT_TEXT("person is hungry: ")
<< field[person_status::hungry]
<< FCPPT_TEXT('\n');
}

As you can see, you can treat a bitfield like an integral type – it has bitwise operator&, operator| and so on. But you can also treat it like a std::map<Enum,bool>.

Classes

struct  fcppt::container::bitfield::hash< Bitfield >
 A hash function for bitfields. More...
 
class  fcppt::container::bitfield::object< ElementType, NumElements, InternalType >
 A statically sized bitfield. More...
 

Typedefs

template<typename NumElements , typename InternalType >
using fcppt::container::bitfield::array = std::array< InternalType, fcppt::brigand::ceil_div< std::size_t, fcppt::cast::size< std::size_t >(NumElements::value), fcppt::container::bitfield::detail::element_bits< std::size_t, InternalType >::value >::value >
 Meta function to retrieve the internal storage type used by fcppt::container::bitfield::object. More...
 
template<typename Enum , typename InternalType = fcppt::container::bitfield::default_internal_type>
using fcppt::container::bitfield::enum_object = fcppt::container::bitfield::object< Enum, typename fcppt::enum_::size< Enum >::type, InternalType >
 Declare a bitfield from an enum. More...
 

Functions

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator== (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Compares two bitfields for equality. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator!= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Compares two bitfields for inequality. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator< (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Compares two bitfields lexicographically bit by bit. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator<= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Compares two bitfields lexicographically bit by bit. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator> (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Compares two bitfields lexicographically bit by bit. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator>= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Compares two bitfields lexicographically bit by bit. More...
 
template<typename Result , typename Function >
Result fcppt::container::bitfield::init (Function const &_function)
 Initialize a bitfield using a function. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > & fcppt::container::bitfield::operator|= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &_left, ElementType const _index)
 Set a bit to true. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > & fcppt::container::bitfield::operator|= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Do a bit-wise "or" for all bits. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > & fcppt::container::bitfield::operator &= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Do a bit-wise "and" for all bits. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > & fcppt::container::bitfield::operator^= (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &_left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Do a bit-wise "xor" for all bits. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > fcppt::container::bitfield::operator~ (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > _field)
 Do a bit-wise "not" for all bits (inverts all bits). More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::value_type fcppt::container::bitfield::operator & (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_field, ElementType const _index)
 Checks if the specified bit is set. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > fcppt::container::bitfield::operator| (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > _field, ElementType const _index)
 Set the specified bit to true. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > fcppt::container::bitfield::operator| (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > _left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Do a bit-wise "or" for all bits. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > fcppt::container::bitfield::operator & (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > _left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Do a bit-wise "and" for all bits. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > fcppt::container::bitfield::operator^ (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > _left, fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_right)
 Do a bit-wise "xor" for all bits. More...
 
template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType >::internal_type fcppt::container::bitfield::underlying_value (fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &_bitfield)
 Returns the underlying value of a bitfield. More...
 

Typedef Documentation

◆ array

template<typename NumElements , typename InternalType >
using fcppt::container::bitfield::array = typedef std::array< InternalType, fcppt::brigand::ceil_div< std::size_t, fcppt::cast::size< std::size_t >( NumElements::value ), fcppt::container::bitfield::detail::element_bits< std::size_t, InternalType >::value >::value >

Meta function to retrieve the internal storage type used by fcppt::container::bitfield::object.

This is currently just an array of as many InternalTypes values as are necessary to hold NumElements bits.

◆ enum_object

template<typename Enum , typename InternalType = fcppt::container::bitfield::default_internal_type>
using fcppt::container::bitfield::enum_object = typedef fcppt::container::bitfield::object< Enum, typename fcppt::enum_::size< Enum >::type, InternalType >

Declare a bitfield from an enum.

Template Parameters
EnumMust be an enum type.
InternalTypeThe internal type to use for the bitfield.

Function Documentation

◆ init()

template<typename Result , typename Function >
Result fcppt::container::bitfield::init ( Function const &  _function)

Initialize a bitfield using a function.

Every bit of Result with index e is set to _function(e).

Template Parameters
ResultMust be a bitfield.
FunctionMust be callable as bool (Result::element_type).

◆ operator &() [1/2]

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::value_type fcppt::container::bitfield::operator& ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _field,
ElementType const  _index 
)

Checks if the specified bit is set.

◆ operator &() [2/2]

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType> fcppt::container::bitfield::operator& ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType >  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Do a bit-wise "and" for all bits.

◆ operator &=()

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType>& fcppt::container::bitfield::operator&= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Do a bit-wise "and" for all bits.

◆ operator!=()

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator!= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Compares two bitfields for inequality.

◆ operator<()

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator< ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Compares two bitfields lexicographically bit by bit.

◆ operator<=()

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator<= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Compares two bitfields lexicographically bit by bit.

◆ operator==()

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator== ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Compares two bitfields for equality.

◆ operator>()

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator> ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Compares two bitfields lexicographically bit by bit.

◆ operator>=()

template<typename ElementType , typename NumElements , typename InternalType >
bool fcppt::container::bitfield::operator>= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Compares two bitfields lexicographically bit by bit.

◆ operator^()

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType> fcppt::container::bitfield::operator^ ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType >  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Do a bit-wise "xor" for all bits.

◆ operator^=()

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType>& fcppt::container::bitfield::operator^= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Do a bit-wise "xor" for all bits.

◆ operator|() [1/2]

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType> fcppt::container::bitfield::operator| ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType >  _field,
ElementType const  _index 
)

Set the specified bit to true.

◆ operator|() [2/2]

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType> fcppt::container::bitfield::operator| ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType >  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Do a bit-wise "or" for all bits.

◆ operator|=() [1/2]

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType>& fcppt::container::bitfield::operator|= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &  _left,
ElementType const  _index 
)

Set a bit to true.

◆ operator|=() [2/2]

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType>& fcppt::container::bitfield::operator|= ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > &  _left,
fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _right 
)

Do a bit-wise "or" for all bits.

◆ operator~()

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType> fcppt::container::bitfield::operator~ ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType >  _field)

Do a bit-wise "not" for all bits (inverts all bits).

◆ underlying_value()

template<typename ElementType , typename NumElements , typename InternalType >
fcppt::container::bitfield::object< ElementType, NumElements, InternalType>::internal_type fcppt::container::bitfield::underlying_value ( fcppt::container::bitfield::object< ElementType, NumElements, InternalType > const &  _bitfield)

Returns the underlying value of a bitfield.

Returns the underlying value of _bitfield. This function can only be called if the bitfield consists of exactly one underlying value (which means that _bitfield::array_size::value == 1u).

Template Parameters
NumElementsMust fit into exactly one object of type InternalType.