regina::BitManipulator< T > Class Template Reference

An optimised class for bitwise analysis and manipulation of native data types. More...

#include <utilities/bitmanip.h>

Inheritance diagram for regina::BitManipulator< T >:

Static Public Member Functions
static constexpr int	bits (T x)
	Returns the number of bits that are set to 1 in the given integer.
static constexpr int	firstBit (T x)
	Returns the index of the first true bit in the given integer, or -1 if the given integer is zero.
static constexpr int	lastBit (T x)
	Returns the index of the last true bit in the given integer, or -1 if the given integer is zero.
static constexpr T	swapBits (T x, int index0, int index1)
	Returns a copy of the given integer with two bits swapped.
static std::partial_ordering	subsetComparison (T x, T y)
	Compares the bits of two integers under the subset relation.
static T	nextPermutation (T x)
	Returns the next largest integer with the same number of true bits as x.

Static Public Attributes
static constexpr bool	specialised = false
	Indicates whether this class is a template specialisation with extra optimisations.

Detailed Description

template<typename T>
class regina::BitManipulator< T >

An optimised class for bitwise analysis and manipulation of native data types.

The class BitManipulator<T> is used to manipulate an integer of type T as a sequence of bits. Here T must be an unsigned native integer type such as unsigned char, unsigned int, or unsigned long long.

Whilst BitManipulator has a generic implementation, all or most native types T have template specialisations that are carefully optimised (precisely what gets specialised depends upon properties of the compiler).

Precondition

Type T is an unsigned integral numeric type whose size in bits is a power of two.

Python

For Python users, the class BitManipulator represents the C++ type BitManipulator<unsigned long>. In particular, you should be aware that BitManipulator is designed specifically to work with native C++ integer types, and cannot handle Python's arbitrary-precision integers. It is up to you to ensure that any Python integers that you pass into the BitManipulator routines are small enough to fit inside a C++ unsigned long.

Member Function Documentation

bits()

template<typename T>

constexpr int regina::BitManipulator< T >::bits ( T x )

inlinestaticconstexpr

Returns the number of bits that are set to 1 in the given integer.

The implementation uses std::popcount() where possible, and a hand-rolled implementation where std::popcount() might be unavailable (e.g., for 128-bit integers).

Parameters

x	the integer of type T to examine.

Returns

the number of bits that are set.

firstBit()

template<typename T>

constexpr int regina::BitManipulator< T >::firstBit ( T x )

inlinestaticconstexpr

Returns the index of the first true bit in the given integer, or -1 if the given integer is zero.

Bits are indexed from 0 upwards, starting at the least significant bit.

Parameters

x	the integer of type T to examine.

Returns

the position of the first true bit, or -1 if there are no true bits.

lastBit()

template<typename T>

constexpr int regina::BitManipulator< T >::lastBit ( T x )

inlinestaticconstexpr

Returns the index of the last true bit in the given integer, or -1 if the given integer is zero.

Bits are indexed from 0 upwards, starting at the least significant bit.

Parameters

x	the integer of type T to examine.

Returns

the position of the last true bit, or -1 if there are no true bits.

nextPermutation()

template<typename T>

T regina::BitManipulatorByType< T >::nextPermutation ( T x )

inlinestaticinherited

Returns the next largest integer with the same number of true bits as x.

If x is the largest such integer (i.e., x is of the form 111...1000...0), then this routine returns 0.

Parameters

x	the integer of type T to examine.

Returns

the next largrst integer with the same number of true bits, or 0 if this is the largest such integer.

subsetComparison()

template<typename T>

std::partial_ordering regina::BitManipulator< T >::subsetComparison ( T x, T y )

inlinestatic

Compares the bits of two integers under the subset relation.

Here x is considered less than y if the bits that are set in x form a strict subset of the bits that are set in y.

Python

Not present. This is not available for Python users, since Python does not have access to the standard C++ type std::partial_ordering, and since there is no "natural" way to present a partial ordering as an integer.

Parameters

x	the first integer to examine.
y	the second integer to examine.

Returns

A three-way comparison result, indicating whether the bits of x are equal to, a strict subset of, a strict superset of, or incomparable to the bits of y. These outcomes are indicated by the return values equivalent, less, greater, and unordered respectively.

swapBits()

template<typename T>

constexpr T regina::BitManipulator< T >::swapBits ( T x, int index0, int index1 )

inlinestaticconstexpr

Returns a copy of the given integer with two bits swapped.

Bits are indexed from 0 upwards, starting at the least significant bit.

The two indices index0 and index1 may be the same (in which case the given bitmask will be returned unchanged).

Parameters

x	the bitmask to examine.
index0	the index of the first bit to swap.
index1	the index of the second bit to swap.

Returns

a copy of x with bits index0 and index1 swapped.

Member Data Documentation

specialised

template<typename T>

bool regina::BitManipulatorByType< T >::specialised = false

staticconstexprinherited

Indicates whether this class is a template specialisation with extra optimisations.

This compile-time constant is set to false for the generic implementation, and true for all specialisations.

---

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

• utilities/bitmanip.h