#include <evo/bits.h>

Detailed Description

template<class T = ulong, class TSize = SizeT>
struct evo::Bits< T, TSize >

Traits and helpers for bit manipulation.

See BitArray for a bit array container.

Template Parameters

T	Chunk value type for storing bits, must be an unsigned integer type or results are undefined
TSize	Size integer type, must be unsigned

Classes
struct	IterState
	Bit array iteration state. More...

Public Types
typedef TSize	Size
	Size integer type. More...

typedef T	Value
	Chunk value type. More...

Static Public Member Functions
static T	align_left (T value, uint count)
	Align bits on right to the left. More...

static T	align_right (T value, uint count)
	Align bits on left to the right. More...

static Size	array_bitsize (Size chunks)
	Calculate array size in bits for number of chunks. More...

static bool	array_checkall (const T *data, Size bitsize)
	Check if all bits are set in bit array. More...

static bool	array_checkall (const T *data, Size bitsize, Size pos, Size count)
	Check if all bits are set in subset of bit array. More...

static bool	array_checkany (const T *data, Size bitsize)
	Check if any bits are set in bit array. More...

static bool	array_checkany (const T *data, Size bitsize, Size pos, Size count)
	Check if any bits are set in subset of bit array. More...

static Size	array_copy (T data, Size bitsize, T src_data, Size src_bitsize, Size src_pos=0, Size src_count=ALL)
	Copy bits from another array. More...

static Size	array_countbits (const T *data, Size bitsize)
	Count number of set bits in bit array. More...

static Size	array_countbits (const T *data, Size bitsize, Size pos, Size count)
	Count number of set bits in subset of bit array. More...

template<class U = uint32>
static U	array_extractl (const T *data, Size bitsize, Size pos, Size count)
	Extract bits from chunked bit array. More...

template<class U = uint32>
static U	array_extractr (const T *data, Size bitsize, Size pos, Size count)
	Extract bits from chunked bit array. More...

static bool	array_get (const T *data, Size bitsize, Size pos)
	Get bit at position from chunked bit array. More...

static Size	array_iter (IterState &state, const T *data, Size bitsize)
	Iterate to first set bit in array. More...

static Size	array_iternext (IterState &state)
	Iterate to next set bit in array. More...

static bool	array_set (T *data, Size bitsize, Size pos, bool value=true)
	Set or clear bit at position in chunked bit array. More...

static Size	array_set_multi (T *data, Size bitsize, Size pos=0, Size count=ALL, bool value=true)
	Set or clear count bits at position in chunked bit array. More...

static void	array_shiftl (T *data, Size bitsize, uint count)
	Shift to the left in chunked bit array. More...

static void	array_shiftr (T *data, Size bitsize, uint count)
	Shift to the right in chunked bit array. More...

static Size	array_size (Size bitsize)
	Calculate array size in chunks for number of bits. More...

template<class U >
static bool	array_store (T *data, Size bitsize, Size pos, Size count, U value)
	Stores bits in chunked bit array. More...

static bool	array_toggle (T *data, Size bitsize, Size pos)
	Toggle bit at position in chunked bit array. More...

static Size	array_toggle_multi (T *data, Size bitsize, Size pos=0, Size count=ALL)
	Toggle count bits at position in chunked bit array. More...

static T	mask (uint start, uint count)
	Get bitmask with `count` bits set from `start` position. More...

static T	safemask (uint start, uint count)
	Get bitmask with `count` bits set from `start` position, with bounds checking for safety. More...

Static Public Attributes
static const T	ALLBITS = T(~ZERO)
	Value with all bits set. More...

static const uint	BITS = BYTES * 8
	Number of bits for type `T` More...

static const uint	BITS_MINUS_1 = BITS - 1
	BITS minus 1, used by bit manipulation code. More...

static const uint	BYTES = sizeof(T)
	Number of bytes for type `T` More...

static const T	LBIT = RBIT << BITS_MINUS_1
	Mask with left-most bit set. More...

static const T	RBIT = 0x01
	Mask with right-most bit set. More...

static const T	ZERO = 0
	Zero value. More...

Member Typedef Documentation

◆ Size

typedef TSize Size

Size integer type.

◆ Value

typedef T Value

Chunk value type.

Member Function Documentation

◆ align_left()

static T align_left	(	T	value,
		uint	count
	)

inlinestatic

Align bits on right to the left.

This shifts so count bits on the right are aligned on the left
Vacated bits on the right are zero-filled

Parameters

value	Value to adjust
count	Number of bits on the right side to align to the left side

Returns: Aligned value, or same value if count is too high

◆ align_right()

static T align_right	(	T	value,
		uint	count
	)

inlinestatic

Align bits on left to the right.

This shifts so count bits on the left are aligned on the right
Vacated bits on the left are zero-filled

Parameters

value	Value to adjust
count	Number of bits on the left side to align to the right side

Returns: Aligned value, or same value if count is too high

◆ array_bitsize()

static Size array_bitsize ( Size chunks )

inlinestatic

Calculate array size in bits for number of chunks.

This is the reverse of array_size()

Parameters

chunks Number of chunks in bit array

Returns: Number of bits for number of chunks

See also: array_size()

◆ array_checkall() [1/2]

static bool array_checkall	(	const T *	data,
		Size	bitsize
	)

inlinestatic

Check if all bits are set in bit array.

This scans and checks that all bits are set, and stops early if a bit isn't set

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array

Returns: Whether all bits are set, false if a bit isn't set, true if empty

◆ array_checkall() [2/2]

static bool array_checkall	(	const T *	data,
		Size	bitsize,
		Size	pos,
		Size	count
	)

inlinestatic

Check if all bits are set in subset of bit array.

This scans and checks that all bits are set in the subset, and stops early if a bit isn't set

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to start at, 0 for first bit on left, etc
count	Number of bits to check from pos, ALL for all from pos

Returns: Whether all bits in subset are set, false if a bit isn't set, true if subset is empty

◆ array_checkany() [1/2]

static bool array_checkany	(	const T *	data,
		Size	bitsize
	)

inlinestatic

Check if any bits are set in bit array.

This scans and checks that at least 1 bit is set, and stops early if a bit is set

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array

Returns: Whether at least 1 bit is set, false if all bits are cleared

◆ array_checkany() [2/2]

static bool array_checkany	(	const T *	data,
		Size	bitsize,
		Size	pos,
		Size	count
	)

inlinestatic

Check if any bits are set in subset of bit array.

This scans and checks that at least 1 bit is set in the subset, and stops early if a bit is set

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to start at, 0 for first bit on left, etc
count	Number of bits to check from pos, ALL for all from pos

Returns: Whether at least 1 bit in subset is set, false if all bits in subset are cleared

◆ array_copy()

static Size array_copy	(	T *	data,
		Size	bitsize,
		T *	src_data,
		Size	src_bitsize,
		Size	src_pos = `0`,
		Size	src_count = `ALL`
	)

inlinestatic

Copy bits from another array.

Bits are counted left-to-right, as if from an array of bools
Bits that don't fit will be truncated

Parameters

data	Bit array data pointer to copy to, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array to copy to
src_data	Source bit array data pointer, treated as a bool array even though bits come in chunks of T
src_bitsize	Number of bits in source bit array
src_pos	Source bit position to copy from, 0 for first bit on left, etc
src_count	Number of bits to copy

Returns: Number of bits copied, may be truncated if out of bounds

See also: array_extract(), array_store()

◆ array_countbits() [1/2]

static Size array_countbits	(	const T *	data,
		Size	bitsize
	)

inlinestatic

Count number of set bits in bit array.

This scans and counts the number of bits set

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array

Returns: Number of bits set, 0 if none

◆ array_countbits() [2/2]

static Size array_countbits	(	const T *	data,
		Size	bitsize,
		Size	pos,
		Size	count
	)

inlinestatic

Count number of set bits in subset of bit array.

This scans and counts the number of bits set in the subset

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to start at, 0 for first bit on left, etc
count	Number of bits to count from pos, ALL for all from pos

Returns: Number of bits set in subset, 0 if none

◆ array_extractl()

static U array_extractl	(	const T *	data,
		Size	bitsize,
		Size	pos,
		Size	count
	)

inlinestatic

Extract bits from chunked bit array.

Bits are stored in chunks but are extracted left-to-right, as if from an array of bools
- This works the same regardless of chunk size, or system endianness
Extracted bits are left-aligned in the return value, and the left-most bit is the "first" bit (as if from an array of bools)
- Example with 3 extracted bits 111 returned as uint8: 11100000

Template Parameters

U	Return type for extracted bits, must be unsigned (uint, ulong, uint32, etc) – defaults to `ulong` in C++11 or newer

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to extract from, 0 for first bit on left, etc
count	Number of bits to extract, truncated if larger than bitsize or return value

Returns: Extracted bits, aligned to the left

See also: array_extractr(), array_get(), array_store()

◆ array_extractr()

static U array_extractr	(	const T *	data,
		Size	bitsize,
		Size	pos,
		Size	count
	)

inlinestatic

Extract bits from chunked bit array.

Bits are stored in chunks but are extracted left-to-right, as if from an array of bools
- This works the same regardless of chunk size, or system endianness
Extracted bits returned are right-aligned so the result is an integer
- Example with 3 extracted bits 111 returned as uint8: 00000111 or 7 in decimal
A count larger than bits in return type will be truncated – this should be avoided as it may not be easy to tell how many bits were truncated
- For example, if you pass count=9 with return type uint8 then this uses count=8
Otherwise count may go out of bit array bounds without truncation – bits from out of bounds are set to 0 and still are right-aligned according to count

Template Parameters

U	Return type for extracted bits, must be unsigned (uint, ulong, uint32, etc) – defaults to `ulong` in C++11 or newer

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to extract from, 0 for first bit on left, etc
count	Number of bits to extract, ALL for num bits in return type, truncated if larger than bits in return type

Returns: Extracted bits, aligned to the right

See also: array_extractl(), array_get(), array_store()

◆ array_get()

static bool array_get	(	const T *	data,
		Size	bitsize,
		Size	pos
	)

inlinestatic

Get bit at position from chunked bit array.

Bits are counted left-to-right, as if from an array of bools

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to get, 0 for first bit on left, etc

Returns: Bit value, false if pos is out of bounds

See also: array_set()

◆ array_iter()

static Size array_iter	(	IterState &	state,
		const T *	data,
		Size	bitsize
	)

inlinestatic

Iterate to first set bit in array.

Bits are counted left-to-right, as if from an array of bools
Call this to find the first set bit, then call array_iternext() with same state repeatedly to find the remaining set bits

Parameters

state	Stores iteration state for calling array_iternext() for next set bit [out]
data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array

Returns: Bit position for first set bit (from left, 0 for first, 1 for second, etc), NONE if no bits set

See also: array_iternext()

◆ array_iternext()

static Size array_iternext ( IterState & state )

inlinestatic

Iterate to next set bit in array.

Bits are counted left-to-right, as if from an array of bools
Call array_iter() first to find first set bit, then call this with same state repeatedly to find the remaining set bits

Parameters

state Stores iteration state while iterating [in/out]

Returns: Bit position for next set bit (from left, 0 for first, 1 for second, etc), NONE if no more bits set

See also: array_iter()

◆ array_set()

static bool array_set	(	T *	data,
		Size	bitsize,
		Size	pos,
		bool	value = `true`
	)

inlinestatic

Set or clear bit at position in chunked bit array.

Bits are counted left-to-right, as if from an array of bools

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to set, 0 for first bit on left, etc
value	Bit value to set, true to set bit, false to clear bit

Returns: Whether successful, false if pos out of bounds

See also: array_set_multi(), array_toggle(), array_get()

◆ array_set_multi()

static Size array_set_multi	(	T *	data,
		Size	bitsize,
		Size	pos = `0`,
		Size	count = `ALL`,
		bool	value = `true`
	)

inlinestatic

Set or clear count bits at position in chunked bit array.

Bits are counted left-to-right, as if from an array of bools

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to set, 0 for first bit on left, etc
count	Number of bits to set from pos, ALL for all from pos
value	Bit value to set, true to set bits, false to clear bits

Returns: Number of bits modified, 0 if out of bounds or count=0

See also: array_set()

◆ array_shiftl()

static void array_shiftl	(	T *	data,
		Size	bitsize,
		uint	count
	)

inlinestatic

Shift to the left in chunked bit array.

New vacated bits on the right are zero-filled

Parameters

data	Bit array data pointer
bitsize	Number of bits in bit array
count	Count to shift, must not be negative

◆ array_shiftr()

static void array_shiftr	(	T *	data,
		Size	bitsize,
		uint	count
	)

inlinestatic

Shift to the right in chunked bit array.

New vacated bits on the left are zero-filled

Parameters

data	Bit array data pointer
bitsize	Number of bits in bit array
count	Count to shift

◆ array_size()

static Size array_size ( Size bitsize )

inlinestatic

Calculate array size in chunks for number of bits.

This figures the number of chunks needed to store given bitcount

Parameters

bitsize Number of bits in bit array

Returns: Number of bit array chunks needed for bitsize

See also: array_bitsize()

◆ array_store()

static bool array_store	(	T *	data,
		Size	bitsize,
		Size	pos,
		Size	count,
		U	value
	)

inlinestatic

Stores bits in chunked bit array.

Bits are stored in chunks but are positioned left-to-right, as if in an array of bools
- This works the same regardless of chunk size, or system endianness
Value bits are taken from the right so integers can be stored
- Example value 00000111 with count=3 would store 111 (3 right-most bits) or 7 in decimal
Bits stored after end of bit array are truncated and lost
Caution: If count exceeds value size, count is capped at that size – only bits from value are stored

Template Parameters

U	Value type to store, signed value is treated as unsigned – inferred from `value` param

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to store at, 0 for first bit on left, etc
count	Number of bits to store from value
value	Value to store (`count` right-most bits are stored)

Returns: Whether successful, false if pos is out of bounds

See also: array_set(), array_extract()

◆ array_toggle()

static bool array_toggle	(	T *	data,
		Size	bitsize,
		Size	pos
	)

inlinestatic

Toggle bit at position in chunked bit array.

Bits are counted left-to-right, as if from an array of bools

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to toggle, 0 for first bit on left, etc

Returns: Whether successful, false if pos out of bounds

See also: array_toggle_multi(), array_set(), array_get()

◆ array_toggle_multi()

static Size array_toggle_multi	(	T *	data,
		Size	bitsize,
		Size	pos = `0`,
		Size	count = `ALL`
	)

inlinestatic

Toggle count bits at position in chunked bit array.

Bits are counted left-to-right, as if from an array of bools

Parameters

data	Bit array data pointer, treated as a bool array even though bits come in chunks of T
bitsize	Number of bits in bit array
pos	Bit position to toggle, 0 for first bit on left, etc
count	Number of bits to toggle from pos, ALL for all from pos

Returns: Number of bits modified, 0 if out of bounds or count=0

See also: array_set()

◆ mask()

static T mask	(	uint	start,
		uint	count
	)

inlinestatic

Get bitmask with count bits set from start position.

Bits are counted left-to-right, as if from an array of bools
Caution: Results are undefined if start or count are out of bounds, see safemask() for safer version

Parameters

start	Mask start position, 0 for first bit on left, etc
count	Number of bits to have set from start

Returns: Mask value with given bits set

See also: safemask()

◆ safemask()

static T safemask	(	uint	start,
		uint	count
	)

inlinestatic

Get bitmask with count bits set from start position, with bounds checking for safety.

Bits are counted left-to-right, as if from an array of bools
This is slightly less efficient than mask() due to added bounds checking

Parameters

start	Mask start position, 0 for first bit on left, etc
count	Number of bits to have set from start, adjusted if out of bounds

Returns: Mask value with given bits set, 0 if start out of bounds or count is 0

See also: mask()

Member Data Documentation

◆ ALLBITS

const T ALLBITS = T(~ZERO)

static

Value with all bits set.

◆ BITS

const uint BITS = BYTES * 8

static

Number of bits for type T

◆ BITS_MINUS_1

const uint BITS_MINUS_1 = BITS - 1

static

BITS minus 1, used by bit manipulation code.

◆ BYTES

const uint BYTES = sizeof(T)

static

Number of bytes for type T

◆ LBIT

const T LBIT = RBIT << BITS_MINUS_1

static

Mask with left-most bit set.

◆ RBIT

const T RBIT = 0x01

static

Mask with right-most bit set.

◆ ZERO

const T ZERO = 0

static

Zero value.

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

evo/bits.h

Detailed Description

template<class T = ulong, class TSize = SizeT> struct evo::Bits< T, TSize >

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Member Typedef Documentation

◆ Size

◆ Value

Member Function Documentation

◆ align_left()

◆ align_right()

◆ array_bitsize()

◆ array_checkall() [1/2]

◆ array_checkall() [2/2]

◆ array_checkany() [1/2]

◆ array_checkany() [2/2]

◆ array_copy()

◆ array_countbits() [1/2]

◆ array_countbits() [2/2]

◆ array_extractl()

◆ array_extractr()

◆ array_get()

◆ array_iter()

◆ array_iternext()

◆ array_set()

◆ array_set_multi()

◆ array_shiftl()

◆ array_shiftr()

◆ array_size()

◆ array_store()

◆ array_toggle()

◆ array_toggle_multi()

◆ mask()

◆ safemask()

Member Data Documentation

◆ ALLBITS

◆ BITS

◆ BITS_MINUS_1

◆ BYTES

◆ LBIT

◆ RBIT

◆ ZERO

template<class T = ulong, class TSize = SizeT>
struct evo::Bits< T, TSize >