Regina 7.4 Calculation Engine
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 >:
regina::BitManipulatorByType< 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 >
static 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
xthe integer of type T to examine.
Returns
the number of bits that are set.

◆ firstBit()

template<typename T >
static 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
xthe 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 >
static 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
xthe 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 >
static 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
xthe 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 >
static 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
xthe first integer to examine.
ythe 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 >
static 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
xthe bitmask to examine.
index0the index of the first bit to swap.
index1the 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: