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	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 T	nextPermutation (T x)
	Returns the next largest integer with the same number of true bits as x.
static constexpr int	bits (T x)
	Returns the number of bits that are set to 1 in the given integer.

Static Public Attributes
static constexpr bool	specialised
	Indicates whether this class is a template specialisation of BitManipulator 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 , unsigned size = sizeof(T)>

static constexpr int regina::BitManipulatorBySize< T, size >::bits ( T x )

inlinestaticconstexprinherited

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

Note that this routine will become redundant once we move to C++20, since we will be able to use std::popcount() instead.

Parameters

x	the 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

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 >

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

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 >

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

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.

Member Data Documentation

specialised

template<typename T >

bool regina::BitManipulator< T >::specialised

staticconstexpr

Initial value:

=
            BitManipulatorByType<T>::specialised ||
            BitManipulatorBySize<T>::specialised

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

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

---

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

• utilities/bitmanip.h