Long bitstrings. More...

#include <bitstring.h>

Public Member Functions
	bitstring ()
	Constructor.

virtual	~bitstring ()
	Destructor.

void	resize (size_t length_in_bits)
	Set the length of the bitstring to length_in_bits. The new valid range is 0.. length_in_bits - 1. More...

size_t	size (void) const
	Return the length (in bits) of the bitstring. More...

void	unsafe_setbit (size_t position)
	Set the bit at position to 1. More...

void	unsafe_unsetbit (size_t position)
	Set the bit at position to 0. More...

bool	unsafe_getbit (size_t position) const
	Return the state (0 or 1) of the bit at the given position. More...

void	setbit (size_t position)
	Set the bit at position to 1. More...

void	unsetbit (size_t position)
	Set the bit at position to 0. More...

bool	getbit (size_t position) const
	Return the state (0 or 1) of the bit at the given position. More...

void	bit_or (bitstring &answer, bitstring &with)
	answer = this \| with More...

void	bit_xor (bitstring &answer, bitstring &with)
	answer = this ^ with More...

void	bit_and (bitstring &answer, bitstring &with)
	answer = this & with More...

void	bit_and_not (bitstring &answer, bitstring &with)
	answer = this & ~with More...

size_t	popcount (void) const
	Return the number of set bits in the bitstring. This uses popcount(bitstring_word) to do the count. More...

size_t	index (size_t which)
	Returns the bit position of the which-th set bit. More...

void	zero (void)
	Set the bitstring to all zeros.

void	one (void)
	Set the bitstring to all ones.

uint8_t *	serialise (size_t &length)
	Return a serialised version of this object as an array of uint8_t. More...

Static Public Member Functions
static size_t	popcount (uint64_t value)
	Count the number of bits set in value. This uses the parallel algorithm from here: https://graphics.stanford.edu/~seander/bithacks.html#CountBitsSetParallel. More...

static size_t	popcount (uint32_t value)

static size_t	popcount (uint16_t value)

static size_t	popcount (uint8_t value)

static void	unittest (void)
	Unit test this class.

Protected Types
enum	action { OR, XOR, AND, AND_NOT }
	The action enum is used to pass a Boolean operation to operation(). More...

typedef uint64_t	bitstring_word
	bitstring_word is used as the underlying type for Boolean operations and for popcount()

Protected Member Functions
virtual void	operation (action op, bitstring &a, bitstring &b, bitstring &c)
	operation More...

Protected Attributes
std::vector< uint8_t >	bits
	The underlying storage for the long bitstring.

size_t	bits_long
	The length of the bitstring in bits.

Detailed Description

Long bitstrings.

The internal storage is in bytes, but they are manipulated in chunks of bitstring::bitstring_word (which were intially uint64_t). The memory used to store the bits is guaranteed to be contigious. The set, unset, and get methods are impemented as function calls because an overloaded operator[] would need to return something that can be assigned to - which would be an inter mediate object that needs to know which bit is being referred to, and that would result in an object creation which is undesirable.

Member Enumeration Documentation

◆ action

enum JASS::bitstring::action

protected

The action enum is used to pass a Boolean operation to operation().

Enumerator
OR	OR two bitstrings together.
XOR	XOR two bitstrings together.
AND	AND two bitstrings together.
AND_NOT	a AND ~ b

Member Function Documentation

◆ bit_and()

void JASS::bitstring::bit_and	(	bitstring &	answer,
		bitstring &	with
	)

inline

answer = this & with

OR this and with, returning the result in answer. This method is used to avoid object copies and allocation that would come from using operator overloading in C++. With is [in, out] because this method sets the length of all three bitstrings to the length of the longest.

Parameters

answer	[out] The answer or this AND with
with	[in, out] the bitstring to AND this with

◆ bit_and_not()

void JASS::bitstring::bit_and_not	(	bitstring &	answer,
		bitstring &	with
	)

inline

answer = this & ~with

OR this and with, returning the result in answer. This method is used to avoid object copies and allocation that would come from using operator overloading in C++. With is [in, out] because this method sets the length of all three bitstrings to the length of the longest.

Parameters

answer	[out] The answer or this AND NOT with
with	[in, out] the bitstring to AND NOT this with

◆ bit_or()

void JASS::bitstring::bit_or	(	bitstring &	answer,
		bitstring &	with
	)

inline

answer = this | with

OR this and with, returning the result in answer. This method is used to avoid object copies and allocation that would come from using operator overloading in C++. With is [in, out] because this method sets the length of all three bitstrings to the length of the longest.

Parameters

answer	[out] The answer or this OR with
with	[in, out] the bitstring to OR this with

◆ bit_xor()

void JASS::bitstring::bit_xor	(	bitstring &	answer,
		bitstring &	with
	)

inline

answer = this ^ with

OR this and with, returning the result in answer. This method is used to avoid object copies and allocation that would come from using operator overloading in C++. With is [in, out] because this method sets the length of all three bitstrings to the length of the longest.

Parameters

answer	[out] The answer or this XOR with
with	[in, out] the bitstring to XOR this with

◆ getbit()

bool JASS::bitstring::getbit ( size_t position ) const

inline

Return the state (0 or 1) of the bit at the given position.

This method checks for overflow and returns false in the case of overflow.

Parameters

position in] Which bit to check.

Returns: true or false, the value of the bit at the given position (or false is position is out of range)

◆ index()

size_t JASS::bitstring::index ( size_t which )

Returns the bit position of the which-th set bit.

Parameters

[in] which set bit we're looking for.

Returns: The bit positon of the given set bit or std::numeric_limits<size_t>::max() if which is greater than the number of set bits.

◆ operation()

void JASS::bitstring::operation	(	action	op,
		bitstring &	a,
		bitstring &	b,
		bitstring &	c
	)

protectedvirtual

operation

Parameters

op	[in] the operation we're going to perform.
a	[out] the answer (b op c)
b	[in] the first parameter
c	in] the second parameter

◆ popcount() [1/5]

static size_t JASS::bitstring::popcount ( uint64_t value )

inlinestatic

Count the number of bits set in value. This uses the parallel algorithm from here: https://graphics.stanford.edu/~seander/bithacks.html#CountBitsSetParallel.

Parameters

value [in] The value whose set bits are counted.

Returns: The number of set bits in the parameter.

◆ popcount() [2/5]

static size_t JASS::bitstring::popcount ( uint32_t value )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ popcount() [3/5]

static size_t JASS::bitstring::popcount ( uint16_t value )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ popcount() [4/5]

static size_t JASS::bitstring::popcount ( uint8_t value )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ popcount() [5/5]

size_t JASS::bitstring::popcount ( void ) const

Return the number of set bits in the bitstring. This uses popcount(bitstring_word) to do the count.

Returns: The number of set bits in this bitstring.

◆ resize()

void JASS::bitstring::resize ( size_t length_in_bits )

Set the length of the bitstring to length_in_bits. The new valid range is 0.. length_in_bits - 1.

Parameters

length_in_bits [in] the new length of bitstring

◆ serialise()

uint8_t* JASS::bitstring::serialise ( size_t & length )

inline

Return a serialised version of this object as an array of uint8_t.

One frequent (and the initial use) of this class is to convert a bit-string into a byte-string. This method does exactly that. It returns a pointer to the internal byte-string and a length. The returned string is contigious. It is valid until the length of the bitstring changes.

Parameters

length [out] The length of the bytestring (measured in bytes).

Returns: The bitstring as a byte string (passed with 0s at the end).

◆ setbit()

void JASS::bitstring::setbit ( size_t position )

inline

Set the bit at position to 1.

This method checks for overflow and has no effect if overflow is detected.

Parameters

position in] Which bit to set to 1.

◆ size()

size_t JASS::bitstring::size ( void ) const

inline

Return the length (in bits) of the bitstring.

Returns: The length of the bitstring measured in bits

◆ unsafe_getbit()

bool JASS::bitstring::unsafe_getbit ( size_t position ) const

inline

Return the state (0 or 1) of the bit at the given position.

This method does not check for overflow and may result in unpredictable behaviour if a position outside the range [0..size()-1] is passed.

Parameters

position in] Which bit to check.

Returns: true or false, the value of the bit at the given position

◆ unsafe_setbit()

void JASS::bitstring::unsafe_setbit ( size_t position )

inline

Set the bit at position to 1.

This method does not check for overflow and may result in unpredictable behaviour if a position outside the range [0..size()-1] is passed.

Parameters

position in] Which bit to set to 1.

◆ unsafe_unsetbit()

void JASS::bitstring::unsafe_unsetbit ( size_t position )

inline

Set the bit at position to 0.

This method does not check for overflow and may result in unpredictable behaviour if a position outside the range [0..size()-1] is passed.

Parameters

position in] Which bit to set to 0.

◆ unsetbit()

void JASS::bitstring::unsetbit ( size_t position )

inline

Set the bit at position to 0.

This method checks for overflow and has no effect if overflow is detected.

Parameters

position in] Which bit to set to 0.

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

source/bitstring.h
source/bitstring.cpp

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ action

Member Function Documentation

◆ bit_and()

◆ bit_and_not()

◆ bit_or()

◆ bit_xor()

◆ getbit()

◆ index()

◆ operation()

◆ popcount() [1/5]

◆ popcount() [2/5]

◆ popcount() [3/5]

◆ popcount() [4/5]

◆ popcount() [5/5]

◆ resize()

◆ serialise()

◆ setbit()

◆ size()

◆ unsafe_getbit()

◆ unsafe_setbit()

◆ unsafe_unsetbit()

◆ unsetbit()