fcppt.container.bitfield

Description

A statically sized bitfield.

Bitfields

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.

A bitfield is used together with an enum type that fulfils the requirements of fcppt.enum.

Here's a small example:

namespace
{
enum class person_status
{
  hungry,
  tired,
  fcppt_maximum = tired // note the extra field here
};
 
using bitfield = fcppt::container::bitfield::object<person_status>;
 
void output(bitfield const &_field)
{
  std::cout << "Person status: hungry: " << (_field & person_status::hungry) << '\n'
            << "Person status: tired: " << (_field & person_status::tired) << '\n';
}
}
 
int main()
{
  // Initialize the bitfield to all zeros
  bitfield field(bitfield::null());
 
  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[]
  std::cout << "person is hungry: " << field[person_status::hungry] << '\n';
 
  // You can also set a flag this way:
  field[person_status::hungry] = false;
 
  std::cout << ("person is hungry: ") << field[person_status::hungry] << '\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, InternalType >
	A statically sized bitfield. More...

Typedefs
template<typename NumElements , typename InternalType >
using	fcppt::container::bitfield::array = fcppt::array::object< InternalType, fcppt::math::ceil_div_static< 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.

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

Typedef Documentation

array

template<typename NumElements , typename InternalType >

using fcppt::container::bitfield::array = typedef fcppt::array::object< InternalType, fcppt::math::ceil_div_static< 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.

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

Result	Must be a bitfield.
Function	Must be callable as bool (Result::element_type).

operator!=()

template<typename ElementType , typename InternalType >

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

Compares two bitfields for inequality.

operator&() [1/2]

template<typename ElementType , typename InternalType >

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

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

operator&() [2/2]

template<typename ElementType , typename InternalType >

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

Checks if the specified bit is set.

operator&=()

template<typename ElementType , typename InternalType >

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

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

operator<<()

template<typename Ch , typename Traits , typename ElementType , typename InternalType >

std::basic_ostream< Ch, Traits > & fcppt::container::bitfield::operator<<	(	std::basic_ostream< Ch, Traits > &	_stream,
		fcppt::container::bitfield::object< ElementType, InternalType > const &	_bitfield
	)

Outputs a bitfield.

operator==()

template<typename ElementType , typename InternalType >

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

Compares two bitfields for equality.

operator^()

template<typename ElementType , typename InternalType >

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

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

operator^=()

template<typename ElementType , typename InternalType >

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

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

operator|() [1/2]

template<typename ElementType , typename InternalType >

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

Set the specified bit to true.

operator|() [2/2]

template<typename ElementType , typename InternalType >

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

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

operator|=() [1/2]

template<typename ElementType , typename InternalType >

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

Set a bit to true.

operator|=() [2/2]

template<typename ElementType , typename InternalType >

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

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

operator~()

template<typename ElementType , typename InternalType >

fcppt::container::bitfield::object< ElementType, InternalType > fcppt::container::bitfield::operator~

(

fcppt::container::bitfield::object< ElementType, InternalType >

_field

)

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

underlying_value()

template<typename ElementType , typename InternalType , typename = std::enable_if_t< fcppt::container::bitfield::object<ElementType, InternalType>::array_size::value == 1U>>

fcppt::container::bitfield::object< ElementType, InternalType >::internal_type fcppt::container::bitfield::underlying_value

(

fcppt::container::bitfield::object< ElementType, 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).