regina::Bitmask1< T > Class Template Reference
Miscellaneous Utilities

A small but extremely fast bitmask class that can store up to 8 * sizeof(T) true-or-false bits. More...

`#include <utilities/bitmask.h>`

## Public Member Functions

| Bitmask1 ()
| Creates a new bitmask with all bits set to `false`. More...
| Bitmask1 (size_t)
| Creates a new bitmask with all bits set to `false`. More...
| Bitmask1 (const Bitmask1< T > &cloneMe)
| Creates a clone of the given bitmask. More...
void | reset ()
| Sets all bits of this bitmask to `false`. More...
void | reset (size_t)
| Sets all bits of this bitmask to `false`. More...
Bitmask1< T > & | operator= (const Bitmask1< T > &other)
| Sets this bitmask to a copy of the given bitmask. More...
void | truncate (size_t numBits)
| Leaves the first numBits bits of this bitmask intact, but sets all subsequent bits to `false`. More...
bool | get (size_t index) const
| Returns the value of the given bit of this bitmask. More...
void | set (size_t index, bool value)
| Sets the given bit of this bitmask to the given value. More...
template<typename ForwardIterator >
void | set (ForwardIterator indexBegin, ForwardIterator indexEnd, bool value)
| Sets all bits in the given sorted list to the given value. More...
Bitmask1< T > & | operator&= (const Bitmask1< T > &other)
| Sets this to the intersection of this and the given bitmask. More...
Bitmask1< T > & | operator|= (const Bitmask1< T > &other)
| Sets this to the union of this and the given bitmask. More...
Bitmask1< T > & | operator^= (const Bitmask1< T > &other)
| Sets this to the exclusive disjunction (XOR) of this and the given bitmask. More...
Bitmask1< T > & | operator-= (const Bitmask1< T > &other)
| Sets this to the set difference of this and the given bitmask. More...
void | flip ()
| Negates every bit in this bitmask. More...
bool | operator== (const Bitmask1< T > &other) const
| Determines whether this and the given bitmask are identical. More...
bool | lessThan (const Bitmask1< T > &other) const
| Determines whether this bitmask appears strictly before the given bitmask when bitmasks are sorted in lexicographical order. More...
bool | operator<= (const Bitmask1< T > &other) const
| Determines whether this bitmask is entirely contained within the given bitmask. More...
bool | inUnion (const Bitmask1< T > &x, const Bitmask1< T > &y) const
| Determines whether this bitmask is entirely contained within the union of the two given bitmasks. More...
bool | containsIntn (const Bitmask1< T > &x, const Bitmask1< T > &y) const
| Determines whether this bitmask contains the intersection of the two given bitmasks. More...
size_t | bits () const
| Returns the number of bits currently set to `true` in this bitmask. More...
long | firstBit () const
| Returns the index of the first `true` bit in this bitmask, or -1 if there are no `true` bits. More...
long | lastBit () const
| Returns the index of the last `true` bit in this bitmask, or -1 if there are no `true` bits. More...
bool | atMostOneBit () const
| Determines whether at most one bit is set to `true` in this bitmask. More...

## Friends

std::ostream & | operator (std::ostream &out, const Bitmask1< T > &mask)

## Detailed Description

### template<typename T>
class regina::Bitmask1< T >

A small but extremely fast bitmask class that can store up to 8 * sizeof(T) true-or-false bits.

This bitmask packs all of the bits together into a single variable of type T. This means that operations on bitmasks are extremely fast, because all of the bits can be processed at once.

The downside of course is that the number of bits that can be stored is limited to 8 * sizeof(T), where T must be a native unsigned integer type (such as unsigned char, unsigned int, or unsigned long long).

For another extremely fast bitmask class that can store twice as many bits, see Bitmask2. For a bitmask class that can store arbitrarily many bits, see Bitmask.

Precondition
  Type T is an unsigned integral numeric type.

Python:
  Not present.

## Constructor & Destructor Documentation

## Bitmask1() [1/3]

template<typename T >

regina::Bitmask1< T >::Bitmask1 | ( |  | ) |

inline

Creates a new bitmask with all bits set to `false`.

## Bitmask1() [2/3]

template<typename T >

regina::Bitmask1< T >::Bitmask1 | ( | size_t |  | ) |

inline

Creates a new bitmask with all bits set to `false`.

The integer argument is merely for compatibility with the Bitmask constructor, and will be ignored.

Warning
  This is not a constructor that initialises the bitmask to a given pattern.

## Bitmask1() [3/3]

template<typename T >

regina::Bitmask1< T >::Bitmask1 | ( | const Bitmask1< T > & | cloneMe | ) |

inline

Creates a clone of the given bitmask.

Parameters

  cloneMe | the bitmask to clone.

## Member Function Documentation

## atMostOneBit()

template<typename T >

bool regina::Bitmask1< T >::atMostOneBit | ( |  | ) | const

inline

Determines whether at most one bit is set to `true` in this bitmask.

If this bitmask is entirely `false` or if only one bit is set to `true`, then this routine will return `true`. Otherwise this routine will return `false`.

Returns
  `true` if and only if at most one bit is set to `true`.

## bits()

template<typename T >

size_t regina::Bitmask1< T >::bits | ( |  | ) | const

inline

Returns the number of bits currently set to `true` in this bitmask.

Returns
  the number of `true` bits.

## containsIntn()

template<typename T >

bool regina::Bitmask1< T >::containsIntn | ( | const Bitmask1< T > & | x,
|  | const Bitmask1< T > & | y
| ) |  | const

inline

Determines whether this bitmask contains the intersection of the two given bitmasks.

For this routine to return `true`, every bit that is set in both x and y must be set in this bitmask also.

Parameters

  x | the first bitmask used to form the intersection.
  y | the first bitmask used to form the intersection.

Returns
  `true` if and only if this bitmask entirely contains the intersection of x and y.

## firstBit()

template<typename T >

long regina::Bitmask1< T >::firstBit | ( |  | ) | const

inline

Returns the index of the first `true` bit in this bitmask, or -1 if there are no `true` bits.

Returns
  the index of the first `true` bit.

## flip()

template<typename T >

void regina::Bitmask1< T >::flip | ( |  | ) |

inline

Negates every bit in this bitmask.

All `true` bits will be set to `false` and vice versa.

Unlike the more generic Bitmask, this optimised bitmask class does not store a length. This means that all 8 * sizeof(T) possible bits will be negated.

## get()

template<typename T >

bool regina::Bitmask1< T >::get | ( | size_t | index | ) | const

inline

Returns the value of the given bit of this bitmask.

Parameters

  index | indicates which bit to query; this must be between 0 and (8 * sizeof(T) - 1) inclusive.

Returns
  the value of the (index)th bit.

## inUnion()

template<typename T >

bool regina::Bitmask1< T >::inUnion | ( | const Bitmask1< T > & | x,
|  | const Bitmask1< T > & | y
| ) |  | const

inline

Determines whether this bitmask is entirely contained within the union of the two given bitmasks.

For this routine to return `true`, every bit that is set in this bitmask must also be set in either x or y.

Parameters

  x | the first bitmask used to form the union.
  y | the first bitmask used to form the union.

Returns
  `true` if and only if this bitmask is entirely contained within the union of x and y.

## lastBit()

template<typename T >

long regina::Bitmask1< T >::lastBit | ( |  | ) | const

inline

Returns the index of the last `true` bit in this bitmask, or -1 if there are no `true` bits.

Returns
  the index of the last `true` bit.

## lessThan()

template<typename T >

bool regina::Bitmask1< T >::lessThan | ( | const Bitmask1< T > & | other | ) | const

inline

Determines whether this bitmask appears strictly before the given bitmask when bitmasks are sorted in lexicographical order.

Here the bit at index 0 is least significant, and the bit at index length-1 is most significant.

Warning
  We do not use < for this operation, since <= represents the subset operation.

Parameters

  other | the bitmask to compare against this.

Returns
  `true` if and only if this is lexicographically strictly smaller than the given bitmask.

## operator&=()

template<typename T >

Bitmask1<T>& regina::Bitmask1< T >::operator &= | ( | const Bitmask1< T > & | other | ) |

inline

Sets this to the intersection of this and the given bitmask.

Every bit that is unset in other will be unset in this bitmask.

Parameters

  other | the bitmask to intersect with this.

Returns
  a reference to this bitmask.

## operator-=()

template<typename T >

Bitmask1<T>& regina::Bitmask1< T >::operator-= | ( | const Bitmask1< T > & | other | ) |

inline

Sets this to the set difference of this and the given bitmask.

Every bit that is set in other will be cleared in this bitmask.

Parameters

  other | the bitmask to XOR with this.

Returns
  a reference to this bitmask.

## operator<=()

template<typename T >

bool regina::Bitmask1< T >::operator<= | ( | const Bitmask1< T > & | other | ) | const

inline

Determines whether this bitmask is entirely contained within the given bitmask.

For this routine to return `true`, every bit that is set in this bitmask must also be set in the given bitmask.

Warning
  This operation does not compare bitmasks lexicographically; moreover, it only describes a partial order, not a total order. To compare bitmasks lexicographically, use lessThan() instead.

Parameters

  other | the bitmask to compare against this.

Returns
  `true` if and only if this bitmask is entirely contained within the given bitmask.

## operator=()

template<typename T >

Bitmask1<T>& regina::Bitmask1< T >::operator= | ( | const Bitmask1< T > & | other | ) |

inline

Sets this bitmask to a copy of the given bitmask.

Parameters

  other | the bitmask to clone.

Returns
  a reference to this bitmask.

## operator==()

template<typename T >

bool regina::Bitmask1< T >::operator== | ( | const Bitmask1< T > & | other | ) | const

inline

Determines whether this and the given bitmask are identical.

Parameters

  other | the bitmask to compare against this.

Returns
  `true` if and only if this and the given bitmask are identical.

## operator^=()

template<typename T >

Bitmask1<T>& regina::Bitmask1< T >::operator^= | ( | const Bitmask1< T > & | other | ) |

inline

Sets this to the exclusive disjunction (XOR) of this and the given bitmask.

Every bit that is set in other will be flipped in this bitmask.

Parameters

  other | the bitmask to XOR with this.

Returns
  a reference to this bitmask.

## operator|=()

template<typename T >

Bitmask1<T>& regina::Bitmask1< T >::operator|= | ( | const Bitmask1< T > & | other | ) |

inline

Sets this to the union of this and the given bitmask.

Every bit that is set in other will be set in this bitmask.

Parameters

  other | the bitmask to union with this.

Returns
  a reference to this bitmask.

## reset() [1/2]

template<typename T >

void regina::Bitmask1< T >::reset | ( |  | ) |

inline

Sets all bits of this bitmask to `false`.

## reset() [2/2]

template<typename T >

void regina::Bitmask1< T >::reset | ( | size_t |  | ) |

inline

Sets all bits of this bitmask to `false`.

The integer argument is merely for compatibility with Bitmask::reset(size_t), and will be ignored.

## set() [1/2]

template<typename T >

void regina::Bitmask1< T >::set | ( | size_t | index,
|  | bool | value
| ) |  |

inline

Sets the given bit of this bitmask to the given value.

Parameters

  index | indicates which bit to set; this must be between 0 and (8 * sizeof(T) - 1) inclusive.
  value | the value that will be assigned to the (index)th bit.

## set() [2/2]

template<typename T >
template<typename ForwardIterator >

void regina::Bitmask1< T >::set | ( | ForwardIterator | indexBegin,
|  | ForwardIterator | indexEnd,
|  | bool | value
| ) |  |

inline

Sets all bits in the given sorted list to the given value.

This is a convenience routine for setting many bits at once. The indices of the bits to set should be sorted and stored in some container, such as a std::set or a C-style array. This routine takes iterators over this container, and sets the bits at the corresponding indices to the given value.

For example, the following code would set bits 3, 5 and 6 to `true:`

std::vector<unsigned> indices;
indices.push(3); indices.push(5); indices.push(6);
bitmask.set(indices.begin(), indices.end(), true);

Likewise, the following code would set bits 1, 4 and 7 to `false:`

unsigned indices[3] = { 1, 4, 7 };
bitmask.set(indices, indices + 3, false);

All other bits of this bitmask are unaffected by this routine.

Precondition
  ForwardIterator is a forward iterator type that iterates over integer values.
  The list of indices described by these iterators is in sorted order. This is to allow optimisations for larger bitmask types.
  All indices in the given list are between 0 and (8 * sizeof(T) - 1) inclusive.

Parameters

  indexBegin | the beginning of the iterator range containing the sorted indices of the bits to set.
  indexEnd | the end of the iterator range containing the sorted indices of the bits to set.
  value | the value that will be assigned to each of the corresponding bits.

## truncate()

template<typename T >

void regina::Bitmask1< T >::truncate | ( | size_t | numBits | ) |

inline

Leaves the first numBits bits of this bitmask intact, but sets all subsequent bits to `false`.

In other words, this routine "truncates" this bitmask to the given number of bits.

This routine does not change the length of this bitmask (as passed to the contructor or to reset()).

Parameters

  numBits | the number of bits that will not be cleared.

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

- utilities/bitmask.h

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).