The Bit Set Interface. More...

#include "private/private_bitset.h"
#include "types.h"

Include dependency graph for bitset.h:

This graph shows which files directly or indirectly include this file:

Detailed Description

The Bit Set Interface.

A bit set offers efficient set membership operations when the range of values can be tracked via an index. Both a fixed size and dynamic variant are possible depending on initialization options.

Conceptually, the bit set can be thought of as an arbitrary length integer with index 0 being the Least Significant Bit and index N - 1 being the Most Significant Bit of the integer. Internally, this is implemented by populating each block of the bit set from Least Significant Bit to Most Significant Bit. Therefore, "trailing" means starting from the Least Significant Bit and "leading" means starting from the Most Significant Bit; this is done to stay consistent with upcoming bit operations introduced to the C23 standard.

A bit set can be used for modeling integer operations on integers that exceed the widths available on one's platform. The provided bitwise operation functions are helpful for these types of manipulations.

A bit set can also be used for modeling data that can be abstracted to a position and binary value. For example, disk blocks in a file system, free blocks in a memory allocator, and many other resource abstractions can benefit from a bit set. For these use cases the bit set offers efficient functions to find the first bits set to zero or one from either the trailing or leading direction. A bit set can also efficiently report if contiguous ranges of zeros or ones are available.

All *_range functions interpret their range input argument parameters as [index, index + count), a starting index and a positive forward length. This convention is consistent for all operations. The implementation automatically chooses the optimal scan direction, Least Significant Bit to Most Significant Bit for trailing scans, Most Significant Bit to Least Significant Bit for leading scans. However, the user always specifies the range in the same way for consistency.

To shorten names in the interface, define the following preprocessor directive at the top of your file.

#define BITSET_USING_NAMESPACE_CCC

All types and functions can then be written without the CCC_ prefix.

Container Initialization
Initialize and create containers with memory and permissions.
#define	CCC_bitset_block_count(bit_capacity) CCC_private_bitset_block_count(bit_capacity)
	Get the number of bit blocks needed for the desired bit set capacity.

#define	CCC_bitset_block_bytes(bit_capacity) CCC_private_bitset_block_bytes(bit_capacity)
	Get the number of bytes needed for the desired bit set capacity.

#define	CCC_bitset_default() CCC_private_bitset_default()
	Initialize an empty default bit set.

#define	CCC_bitset_with_storage( count, compound_literal_array, optional_storage_specifier...)
	Initialize the bit set with a starting capacity and size at runtime or compile time with no allocation permissions or context from a compound literal of bitset blocks.

#define	CCC_bitset_from( allocator, start_string_index, count, bit_on_char, input_string, optional_capacity...)
	Initialize the bit set with a custom input string.

#define	CCC_bitset_with_capacity(allocator, capacity, optional_count...) CCC_private_bitset_with_capacity(allocator, capacity, optional_count)
	Initialize the bit set with a starting capacity and size at runtime.

#define	CCC_bitset_storage_for( bit_compound_literal_array, optional_storage_specifier...)
	Create the underlying fixed size storage for a bit set given a compound literal array of bits the user wishes to store.

#define	CCC_bitset_for(cap, count, bitblock_pointer...) CCC_private_bitset_for(cap, count, bitblock_pointer)
	Initialize a bit set from any memory source at runtime.

enum	: size_t { CCC_BITSET_BLOCK_BITS = CCC_PRIVATE_BITSET_BLOCK_BITS }

CCC_Result	CCC_bitset_copy (CCC_Bitset destination, CCC_Bitset const source, CCC_Allocator const *allocator)
	Copy the bit set at source to destination.

CCC_Result	CCC_bitset_reserve (CCC_Bitset bitset, size_t to_add, CCC_Allocator const allocator)
	Reserves space for at least to_add more bits.

Container Types
Types available in the container interface.
typedef uint8_t	CCC_Bit
	A type to represent a single bit in the bit set.

typedef struct CCC_Bitset	CCC_Bitset
	The bit set type that may be stored and initialized on the stack, heap, or data segment at compile or run time.

Bit Membership Interface
Test for the presence of bits.
CCC_Tribool	CCC_bitset_test (CCC_Bitset const *bitset, size_t index)
	Test the bit at index index for boolean status (CCC_TRUE or CCC_FALSE).

Bit Modification Interface
Set and flip bits in the set.
CCC_Tribool	CCC_bitset_set (CCC_Bitset *bitset, size_t index, CCC_Tribool bit)
	Set the bit at valid index index to value bit (true or false).

CCC_Result	CCC_bitset_set_all (CCC_Bitset *bitset, CCC_Tribool bit)
	Set all the bits to the provided value (CCC_TRUE or CCC_FALSE).

CCC_Result	CCC_bitset_set_range (CCC_Bitset *bitset, size_t range_start_index, size_t range_bit_count, CCC_Tribool bit)
	Set all the bits in the specified range starting at the Least Significant Bit of the range and ending at the Most Significant Bit of the range (CCC_TRUE or CCC_FALSE).

CCC_Tribool	CCC_bitset_reset (CCC_Bitset *bitset, size_t index)
	Set the bit at valid index index to boolean value b (true or false).

CCC_Result	CCC_bitset_reset_all (CCC_Bitset *bitset)
	Set all the bits to CCC_FALSE.

CCC_Result	CCC_bitset_reset_range (CCC_Bitset *bitset, size_t range_start_index, size_t range_bit_count)
	Set all the bits in the specified range starting at the Least Significant Bit of the range and ending at the Most Significant Bit of the range to CCC_FALSE.

CCC_Tribool	CCC_bitset_flip (CCC_Bitset *bitset, size_t index)
	Toggle the bit at index i.

CCC_Result	CCC_bitset_flip_all (CCC_Bitset *bitset)
	Toggle all of the bits to their opposing boolean value.

CCC_Result	CCC_bitset_flip_range (CCC_Bitset *bitset, size_t range_start_index, size_t range_bit_count)
	Flip all the bits in the range, starting at the Least Significant Bit in range and ending at the Most Significant Bit, to their opposite value.

Bit Scan Interface
Find bits with a specific status.
CCC_Tribool	CCC_bitset_any (CCC_Bitset const *bitset)
	Return true if any bits in set are 1.

CCC_Tribool	CCC_bitset_any_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return true if any bits are 1 in the range `[index, index + count)`.

CCC_Tribool	CCC_bitset_none (CCC_Bitset const *bitset)
	Return true if all bits are set to 0.

CCC_Tribool	CCC_bitset_none_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return true if all bits are 0 in the range `[index, index + count)`.

CCC_Tribool	CCC_bitset_all (CCC_Bitset const *bitset)
	Return true if all bits in set are 1.

CCC_Tribool	CCC_bitset_all_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return true if all bits are set to 1 in the range `[index, index + count)`.

CCC_Count	CCC_bitset_first_trailing_one (CCC_Bitset const *bitset)
	Return the index of the first trailing bit set to 1 in the set.

CCC_Count	CCC_bitset_first_trailing_one_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return the index of the first trailing bit set to 1 in the range `[i, index + count)`.

CCC_Count	CCC_bitset_first_trailing_ones (CCC_Bitset const *bitset, size_t ones_count)
	Returns the index of the start of the first trailing number of contiguous 1 bits.

CCC_Count	CCC_bitset_first_trailing_ones_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count, size_t ones_count)
	Returns the index of the start of the first trailing number of contiguous 1 bits in the range `[index, index + count)`.

CCC_Count	CCC_bitset_first_trailing_zero (CCC_Bitset const *bitset)
	Return the index of the first bit set to 0 in the set.

CCC_Count	CCC_bitset_first_trailing_zero_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return the index of the first bit set to 0 in the range `[i, index + count)`.

CCC_Count	CCC_bitset_first_trailing_zeros (CCC_Bitset const *bitset, size_t zeros_count)
	Returns the index of the start of the first trailing number of contiguous 0 bits in the set.

CCC_Count	CCC_bitset_first_trailing_zeros_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count, size_t zeros_count)
	Returns the index of the start of the first trailing zeros_count contiguous 0 bits in the range `[i, index + count)`.

CCC_Count	CCC_bitset_first_leading_one (CCC_Bitset const *bitset)
	Return the index of the first leading bit set to 1 in the set, starting from the Most Significant Bit at index size - 1.

CCC_Count	CCC_bitset_first_leading_one_range (CCC_Bitset const *bitset, size_t index, size_t count)
	Return the index of the first leading bit set to 1 in the range `[i, index + count)`.

CCC_Count	CCC_bitset_first_leading_ones (CCC_Bitset const *bitset, size_t ones_count)
	Returns the index of the start of the first leading bit_count contiguous 1 bits.

CCC_Count	CCC_bitset_first_leading_ones_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count, size_t ones_count)
	Returns the index of the start of the first leading bit_count contiguous 1 bits in the range `[i, index + count)`.

CCC_Count	CCC_bitset_first_leading_zero (CCC_Bitset const *bitset)
	Return the index of the first leading bit set to 0 in the set, starting from the Most Significant Bit at index size - 1.

CCC_Count	CCC_bitset_first_leading_zero_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return the index of the first leading bit set to 0 in the range `[i, index + count)`.

CCC_Count	CCC_bitset_first_leading_zeros (CCC_Bitset const *bitset, size_t zeros_count)
	Returns the index of the start of the first leading number of contiguous 0 bits.

CCC_Count	CCC_bitset_first_leading_zeros_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count, size_t zeros_count)
	Returns the index of the start of the first leading number of contiguous 0 bits in the range `[i, index + count)`.

Bit Operations Interface
Use standard integer width bit operations on the entire set.
CCC_Result	CCC_bitset_or (CCC_Bitset destination, CCC_Bitset const source)
	Bitwise OR destination set with source set.

CCC_Result	CCC_bitset_and (CCC_Bitset destination, CCC_Bitset const source)
	Bitwise AND destination set with source set.

CCC_Result	CCC_bitset_xor (CCC_Bitset destination, CCC_Bitset const source)
	Bitwise XOR destination set with source set.

CCC_Result	CCC_bitset_shift_left (CCC_Bitset *bitset, size_t left_shifts)
	Shift the bit set left by left_shifts amount.

CCC_Result	CCC_bitset_shift_right (CCC_Bitset *bitset, size_t right_shifts)
	Shift the bit set right by right_shifts amount.

CCC_Tribool	CCC_bitset_is_equal (CCC_Bitset const left, CCC_Bitset const right)
	Checks two bit sets of the same size (not capacity) for equality.

Set Operations Interface
Perform basic mathematical set operations on the bit set.
CCC_Tribool	CCC_bitset_is_proper_subset (CCC_Bitset const subset, CCC_Bitset const set)
	Return CCC_TRUE if subset is a proper subset of set (subset ⊂ set).

CCC_Tribool	CCC_bitset_is_subset (CCC_Bitset const subset, CCC_Bitset const set)
	Return CCC_TRUE if subset is a subset of set (subset ⊆ set).

State Interface
Obtain state from the container.
void *	CCC_bitset_data (CCC_Bitset const *bitset)
	Return a reference to the base of the underlying block array.

CCC_Count	CCC_bitset_capacity (CCC_Bitset const *bitset)
	Return total number of bits the capacity of the set can hold.

CCC_Count	CCC_bitset_count (CCC_Bitset const *bitset)
	Return total number of bits actively tracked by the user and set.

CCC_Count	CCC_bitset_blocks_capacity (CCC_Bitset const *bitset)
	Return number of CCC_bitblocks used by bit set for capacity bits.

CCC_Count	CCC_bitset_blocks_count (CCC_Bitset const *bitset)
	Return number of CCC_bitblocks used by the bit set for size bits.

CCC_Tribool	CCC_bitset_is_empty (CCC_Bitset const *bitset)
	Return true if no bits are actively tracked by the user and set.

CCC_Count	CCC_bitset_popcount (CCC_Bitset const *bitset)
	Return the number of bits set to CCC_TRUE. O(n).

CCC_Count	CCC_bitset_popcount_range (CCC_Bitset const *bitset, size_t range_start_index, size_t range_bit_count)
	Return the number of bits set to CCC_TRUE in the range. O(n).

Destructor Interface
Clear the set and manage its memory.
CCC_Result	CCC_bitset_clear (CCC_Bitset *bitset)
	Clears the bit set by setting the size to 0 and all bits to 0. The underlying memory capacity remains unchanged.

CCC_Result	CCC_bitset_clear_and_free (CCC_Bitset bitset, CCC_Allocator const allocator)
	Clears the bit set by setting the size to 0 and freeing the underlying memory. Capacity becomes 0 as well.

Dynamic Interface
Allows adding to and removing from the set.
CCC_Result	CCC_bitset_push_back (CCC_Bitset bitset, CCC_Tribool bit, CCC_Allocator const allocator)
	Append a bit value to the set as the new Most Significant Bit.

CCC_Tribool	CCC_bitset_pop_back (CCC_Bitset *bitset)
	Remove the Most Significant Bit from the set.

Macro Definition Documentation

◆ CCC_bitset_block_bytes

#define CCC_bitset_block_bytes ( bit_capacity ) CCC_private_bitset_block_bytes(bit_capacity)

Get the number of bytes needed for the desired bit set capacity.

Parameters

[in] bit_capacity the number of bits representing this bit set.

Returns: the number of bytes needed to support the bit capacity. This is the number of bytes occupied by the number of bit blocks that must be allocated.

◆ CCC_bitset_block_count

#define CCC_bitset_block_count ( bit_capacity ) CCC_private_bitset_block_count(bit_capacity)

Get the number of bit blocks needed for the desired bit set capacity.

Parameters

[in] bit_capacity the number of bits representing this bit set.

Returns: the number of blocks needed for the desired bit set.

Warning: bit_capacity must be >= 1.

◆ CCC_bitset_default

#define CCC_bitset_default ( ) CCC_private_bitset_default()

Initialize an empty default bit set.

Returns: the initialized bit set on the right side of an equality operator

◆ CCC_bitset_for

#define CCC_bitset_for	(	cap,
		count,
		bitblock_pointer...
	)	CCC_private_bitset_for(cap, count, bitblock_pointer)

Initialize a bit set from any memory source at runtime.

Parameters

[in]	cap	the number of bits that will be stored in this bit set.
[in]	count	the starting count. Set equal to cap for non-dynamic bit set.
[in]	bitblock_pointer	the non-NULL pointer to existing blocks.

Returns: the initialized bit set on the right hand side of an equality operator

Warning: The bit block pointer is assumed to be non-NULL.; In most cases this is the wrong initializer to use. For dynamic bitsets, using the CCC_bitset_with_capacity() is better. For fixed size bitsets with a capacity known at compile time, the CCC_bitset_with_storage() is better. This initializer is in place to support uninitialized heap or stack memory that the user obtains without the help of the bitset API. Therefore, it can only be used at runtime because it must zero out the bitset blocks.

A bitset dynamically allocated at runtime by the user.

int
main(void)
{
    void *const storage = malloc(
        sizeof(CCC_bitset_storage_for((CCC_Bit[4096]){}))
    );
    defer free(storage);
    CCC_Bitset bitset = CCC_bitset_for(
        4096
        4096,
        storage
    );
    return 0;
}

See the more specific initializers for standard usage.

◆ CCC_bitset_from

#define CCC_bitset_from	(	allocator,
		start_string_index,
		count,
		bit_on_char,
		input_string,
		optional_capacity...
	)

Value:

    CCC_private_bitset_from(                                                   \
        allocator,                                                             \
        start_string_index,                                                    \
        count,                                                                 \
        bit_on_char,                                                           \
        input_string,                                                          \
        optional_capacity                                                      \
    )

Initialize the bit set with a custom input string.

Parameters

[in]	allocator	the allocator for memory.
[in]	start_string_index	the index of the input string to start reading is CCC_Tribool input.
[in]	count	number of characters to read from start_string_index.
[in]	bit_on_char	the character that when encountered equates to CCC_TRUE and results in the corresponding bit in the bit set being set CCC_TRUE. Any other character encountered results in the corresponding bit being set to CCC_FALSE.
[in]	input_string	the string literal or pointer to a string.
[in]	optional_capacity	the custom capacity other than the count passed to this initializer. If a greater capacity than the input string is desired because more bits will be pushed later, specify with this input. If this input is less than count, count becomes the capacity.

Returns: the initialized bit set on the right hand side of an equality operator with count bits pushed. If the string ends early due to a null terminator, the count will be less than that passed as input. This can be checked by checking the CCC_bitset_count() function.

Warning: the input string is assumed to adhere to the count. If the string is shorter than the count input and not null terminated the behavior is undefined.

A dynamic bit set with input string pushed.

#define BITSET_USING_NAMESPACE_CCC

Bitset bitset = bitset_from(std_allocator, 0, 4, '1', "1011");

A dynamic bit set that allocates greater capacity.

#define BITSET_USING_NAMESPACE_CCC

Bitset bitset = bitset_from(std_allocator, 0, 4, 'A', "GCAT", 4096);

This initializer is only available to dynamic bit sets due to the inability to run such input code at compile time.

◆ CCC_bitset_storage_for

#define CCC_bitset_storage_for	(	bit_compound_literal_array,
		optional_storage_specifier...
	)

Value:

    CCC_private_bitset_storage_for(                                            \
        bit_compound_literal_array, optional_storage_specifier                 \
    )

Create the underlying fixed size storage for a bit set given a compound literal array of bits the user wishes to store.

Parameters

[in]	bit_compound_literal_array	a compound literal array of `CCC_Bit` representing the number of bits the user wishes to store in the bit set.
[in]	optional_storage_specifier	a storage specifier for the backing block storage may be added on newer compilers.

Warning: This should rarely be used. If a fixed size bit set is desired simply use the CCC_bitset_with_storage() initializer. For dynamic bit sets, there are also many other options.

This macro is required to support the edge case for the user allocating a fixed size bit set dynamically from an allocator at runtime. In this case, the user needs access to the underlying bit set blocks storage object to know how many bytes to allocate. See the below example.

int
main(void)
{
    void *const storage = malloc(
        sizeof(CCC_bitset_storage_for((CCC_Bit[4096]){}))
    );
    defer free(storage);
    CCC_Bitset bitset = CCC_bitset_for(
        NULL,
        NULL,
        4096,
        storage
    );
    return 0;
}

Usually, using a dynamic bit set and the reserve interface would be sufficient. However, the reserve interface only guarantees that at least the needed bytes are allocated. When the user must know the exact size of the backing object due to strict memory requirements, this is helpful. Such a use case may be rare, but must be supported by this container.

◆ CCC_bitset_with_capacity

#define CCC_bitset_with_capacity	(	allocator,
		capacity,
		optional_count...
	)	CCC_private_bitset_with_capacity(allocator, capacity, optional_count)

Initialize the bit set with a starting capacity and size at runtime.

Parameters

[in]	allocator	a pointer to CCC_Allocator for resizing.
[in]	capacity	the number of bits that will be stored in this bit set.
[in]	optional_count	an optional starting size <= capacity. This value defaults to the same value as capacity which is appropriate for most cases. For any case where this is not desirable, set the size manually (for example, a bit set that will push bits back would have a non-zero capacity and 0 count).

Returns: the initialized bit set on the right hand side of an equality operator

A fixed size bit set with size equal to capacity.

#define BITSET_USING_NAMESPACE_CCC
int
main(void)
{
    Bitset bitset = bitset_with_capacity(std_allocator, 4096);
}

A bit set with dynamic push and pop.

#define BITSET_USING_NAMESPACE_CCC
int
main(void)
{
    Bitset bitset = bitset_with_capacity(std_allocator, 4096, 0);
}

This initialization can only be used at runtime. See the normal initializer for static and stack based initialization options.

◆ CCC_bitset_with_storage

#define CCC_bitset_with_storage	(	count,
		compound_literal_array,
		optional_storage_specifier...
	)

Value:

    CCC_private_bitset_with_storage(                                           \
        count, compound_literal_array, optional_storage_specifier              \
    )

Initialize the bit set with a starting capacity and size at runtime or compile time with no allocation permissions or context from a compound literal of bitset blocks.

Parameters

[in]	count	the count of bits <= capacity of this bit set.
[in]	compound_literal_array	the compound literal of CCC_Bit specifying the desired bit count for the bit set. A platform specific array of fixed width integers is constructed to accommodate this bit count.
[in]	optional_storage_specifier	a storage specifier for the backing block storage may be added on newer compilers.

Returns: the initialized bit set on the right hand side of an equality operator Capacity will be set to the full capacity available for the compound literal.

A fixed size bit set.

#define BITSET_USING_NAMESPACE_CCC
static Bitset bitset = bitset_with_storage(
    4096,
    (Bit[4096]){}
);

This saves some initialization boilerplate.

Typedef Documentation

◆ CCC_Bit

typedef uint8_t CCC_Bit

A type to represent a single bit in the bit set.

This is used to pass a compound literal of desired bits to various initializers and macros. The bit set is then custom built to accommodate this bit count with platform specific blocks of fixed width integers.

◆ CCC_Bitset

typedef struct CCC_Bitset CCC_Bitset

The bit set type that may be stored and initialized on the stack, heap, or data segment at compile or run time.

A bit set offers fast membership testing and bit range manipulations when the data can be modeled as a 0-indexed key value data set. In the case of a bit set the key is the index in the bit set and the value is 1 or 0. Operations on single bits occur in O(1) time. All scanning operations operate in O(N) time.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum : size_t

Enumerator
CCC_BITSET_BLOCK_BITS	The number of bits in a block of the bit set.

Function Documentation

◆ CCC_bitset_all()

CCC_Tribool CCC_bitset_all ( CCC_Bitset const * bitset )

Return true if all bits in set are 1.

Parameters

[in] bitset a pointer to the bit set.

Returns: CCC_TRUE if all bits are 1, CCC_FALSE if any bits are 0, CCC_TRIBOOL_ERROR if bitset is NULL.

◆ CCC_bitset_all_range()

CCC_Tribool CCC_bitset_all_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return true if all bits are set to 1 in the range [index, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting position.
[in]	range_bit_count	the size of the range to check.

Returns: CCC_TRUE if all bits are 1, CCC_FALSE if any bits are 0, CCC_TRIBOOL_ERROR if bitset is NULL, index is invalid, count is invalid, or both index and count are invalid.

◆ CCC_bitset_and()

CCC_Result CCC_bitset_and	(	CCC_Bitset *	destination,
		CCC_Bitset const *	source
	)

Bitwise AND destination set with source set.

Parameters

[in]	destination	the set to modified with the AND operation.
[in]	source	the set to be read as the source bits for the AND operation.

Returns: an OK result if the operation is successful or an input error if destination or source are NULL.

Warning: sets behave identically to integers for the AND operation when widening occurs. If destination is larger than source, source is padded with zeros in its Most Significant Bits. This means a bitwise AND operations will occur with the higher order bits in destination and 0's in this padded range (this results in all bits in destination being set to 0 in that range).

Note that sets are aligned from their Least Significant Bit and a smaller source set is conceptually padded with 0's in its higher order bits to align with the larger destination set (no modifications to the smaller set are performed to achieve this). This is done to stay consistent with integer promotion and widening rules in C.

◆ CCC_bitset_any()

CCC_Tribool CCC_bitset_any ( CCC_Bitset const * bitset )

Return true if any bits in set are 1.

Parameters

[in] bitset a pointer to the bit set.

Returns: CCC_TRUE if any bits are 1, CCC_FALSE if no bits are 1, CCC_TRIBOOL_ERROR if bitset is NULL.

◆ CCC_bitset_any_range()

CCC_Tribool CCC_bitset_any_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return true if any bits are 1 in the range [index, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting position.
[in]	range_bit_count	the size of the range to check.

Returns: CCC_TRUE if any bits are 1, CCC_FALSE if no bits are 1, CCC_TRIBOOL_ERROR if bitset is NULL, index is invalid, count is invalid, or both index and count are invalid.

◆ CCC_bitset_blocks_capacity()

CCC_Count CCC_bitset_blocks_capacity ( CCC_Bitset const * bitset )

Return number of CCC_bitblocks used by bit set for capacity bits.

Parameters

[in] bitset a pointer to the bit set.

Returns: an OK(0) status and the capacity in number of bit blocks used to hold the entire capacity of bits in the set. If bs is NULL an argument error is set.

Capacity may be greater than or equal to size.

◆ CCC_bitset_blocks_count()

CCC_Count CCC_bitset_blocks_count ( CCC_Bitset const * bitset )

Return number of CCC_bitblocks used by the bit set for size bits.

Parameters

[in] bitset a pointer to the bit set.

Returns: size in number of bit blocks used to hold the current size of bits in the set. An argument error is set if bitset is NULL.

Size may be less than or equal to capacity.

◆ CCC_bitset_capacity()

CCC_Count CCC_bitset_capacity ( CCC_Bitset const * bitset )

Return total number of bits the capacity of the set can hold.

Parameters

[in] bitset a pointer to the bit set.

Returns: an OK(0) status and the capacity of bits capable of being stored in the current set. If bitset is NULL an argument error is set.

◆ CCC_bitset_clear()

CCC_Result CCC_bitset_clear ( CCC_Bitset * bitset )

Clears the bit set by setting the size to 0 and all bits to 0. The underlying memory capacity remains unchanged.

Parameters

[in] bitset a pointer to the bit set.

Returns: the result of the clear operation, error is returned if bs is NULL .

◆ CCC_bitset_clear_and_free()

CCC_Result CCC_bitset_clear_and_free	(	CCC_Bitset *	bitset,
		CCC_Allocator const *	allocator
	)

Clears the bit set by setting the size to 0 and freeing the underlying memory. Capacity becomes 0 as well.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	allocator	the CCC_Allocator to free memory.

Returns: the result of the clear operation, error is returned if bs is NULL or the set cannot be freed because no allocation function was provided upon initialization.

◆ CCC_bitset_copy()

CCC_Result CCC_bitset_copy	(	CCC_Bitset *	destination,
		CCC_Bitset const *	source,
		CCC_Allocator const *	allocator
	)

Copy the bit set at source to destination.

Parameters

[in]	destination	the initialized destination for the copy of the source set.
[in]	source	the initialized source of the set.
[in]	allocator	the optional allocator if resizing is needed.

Returns: the result of the copy operation. If the destination capacity is less than the source capacity and no allocation function is provided an input error is returned. If resizing is required and resizing of destination fails a memory error is returned.

Note: destination must have capacity greater than or equal to source. If destination capacity is less than source, an allocation function must be provided with the allocate argument.

Note that there are two ways to copy data from source to destination: provide sufficient memory and pass NULL as allocate, or allow the copy function to take care of allocation for the copy.

Manual memory management with no allocation function provided.

#define BITSET_USING_NAMESPACE_CCC
static Bitset source = bitset_with_storage(
    11,
    (Bit[11]){}
);
set_rand_bits(&source);
static Bitset source = bitset_with_storage(
    13
    (Bit[13]){}
);
CCC_Result res = bitset_copy(&destination, &source, &(CCC_Allocator){});

The above requires destination capacity be greater than or equal to source capacity. Here is memory management handed over to the copy function.

#define BITSET_USING_NAMESPACE_CCC
static Bitset source = bitset_default();
push_rand_bits(&source, &std_allocator);
static Bitset source = bitset_default();
CCC_Result res = bitset_copy(&destination, &source, &std_allocator);

These options allow users to stay consistent across containers with their memory management strategies.

◆ CCC_bitset_count()

CCC_Count CCC_bitset_count ( CCC_Bitset const * bitset )

Return total number of bits actively tracked by the user and set.

Parameters

[in] bitset a pointer to the bit set.

Returns: an OK(0) status and the total number of bits currently tracked by the set regardless of true or false state of each. If bitset is NULL an argument error is set.

◆ CCC_bitset_data()

void * CCC_bitset_data ( CCC_Bitset const * bitset )

Return a reference to the base of the underlying block array.

Parameters

[in] bitset a pointer to the bit set.

Returns: a reference to the base of the first block of the bit set block array or NULL if bitset is NULL or has no capacity.

Every block populates bits from Least Significant Bit (LSB) to Most Significant Bit (MSB) so this reference is to the base or LSB of the entire set.

◆ CCC_bitset_first_leading_one()

CCC_Count CCC_bitset_first_leading_one ( CCC_Bitset const * bitset )

Return the index of the first leading bit set to 1 in the set, starting from the Most Significant Bit at index size - 1.

Parameters

[in] bitset a pointer to the bit set.

Returns: the index of the first leading bit set to 1 or CCC_RESULT_FAIL if no 1 bit is found or bitset in NULL.

◆ CCC_bitset_first_leading_one_range()

CCC_Count CCC_bitset_first_leading_one_range	(	CCC_Bitset const *	bitset,
		size_t	index,
		size_t	count
	)

Return the index of the first leading bit set to 1 in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	index	the starting index to search.
[in]	count	the size of the range to check from index towards index 0.

Returns: the index of the first leading bit set to 1 or CCC_RESULT_FAIL if no 1 bit is found, bitset is NULL, or the range is invalid.

◆ CCC_bitset_first_leading_ones()

CCC_Count CCC_bitset_first_leading_ones	(	CCC_Bitset const *	bitset,
		size_t	ones_count
	)

Returns the index of the start of the first leading bit_count contiguous 1 bits.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	ones_count	the number of leading contiguous 1 bits to find.

Returns: an OK(0) status and the starting index of the count of requested bits within the provided set. The returned index is the most significant bit in the range [returned_index, returned_index - ones_count). If such a sequence cannot be found CCC_RESULT_FAIL is set. If bitset is NULL or any argument is out of range an argument error is set.

◆ CCC_bitset_first_leading_ones_range()

CCC_Count CCC_bitset_first_leading_ones_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count,
		size_t	ones_count
	)

Returns the index of the start of the first leading bit_count contiguous 1 bits in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search.
[in]	range_bit_count	the size of the range to check.
[in]	ones_count	the number of leading contiguous 1 bits to find.

Returns: an OK(0) status and the starting index of the count of requested bits within the provided range. The returned index is the most significant bit in the range [returned_index, returned_index - ones_count). If such a sequence cannot be found CCC_RESULT_FAIL is set. If bitset is NULL or any argument is out of range an argument error is set.

◆ CCC_bitset_first_leading_zero()

CCC_Count CCC_bitset_first_leading_zero ( CCC_Bitset const * bitset )

Return the index of the first leading bit set to 0 in the set, starting from the Most Significant Bit at index size - 1.

Parameters

[in] bitset a pointer to the bit set.

Returns: an OK(0) status and the index of the first bit set to 0 or CCC_RESULT_FAIL if no 1 bit is found. If bitset in NULL an argument error is set.

◆ CCC_bitset_first_leading_zero_range()

CCC_Count CCC_bitset_first_leading_zero_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return the index of the first leading bit set to 0 in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search for a 0 bit.
[in]	range_bit_count	size to search from Most Significant Bit to Least in range.

Returns: an OK(0) status and the index of the first bit set to 0 in the specified range CCC_RESULT_FAIL if no 0 bit is found. If bs in NULL an argument error is set.

◆ CCC_bitset_first_leading_zeros()

CCC_Count CCC_bitset_first_leading_zeros	(	CCC_Bitset const *	bitset,
		size_t	zeros_count
	)

Returns the index of the start of the first leading number of contiguous 0 bits.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	zeros_count	the number of leading contiguous 0 bits to find.

Returns: an OK(0) status and the starting index of the count of requested bits within the provided set. The returned index is the most significant bit in the range [returned_index, returned_index - zeros_count). If such a sequence cannot be found CCC_RESULT_FAIL is set. If bitset is NULL or any argument is out of range an argument error is set.

◆ CCC_bitset_first_leading_zeros_range()

CCC_Count CCC_bitset_first_leading_zeros_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count,
		size_t	zeros_count
	)

Returns the index of the start of the first leading number of contiguous 0 bits in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search.
[in]	range_bit_count	the size of the range to check.
[in]	zeros_count	the number of leading contiguous 0 bits to find.

Returns: an OK(0) status and the starting index of the count of requested bits within the provided range. The returned index is the most significant bit in the range [returned_index, returned_index - zeros_count). If such a sequence cannot be found CCC_RESULT_FAIL is set. If bitset is NULL or any argument is out of range an argument error is set.

◆ CCC_bitset_first_trailing_one()

CCC_Count CCC_bitset_first_trailing_one ( CCC_Bitset const * bitset )

Return the index of the first trailing bit set to 1 in the set.

Parameters

[in] bitset a pointer to the bit set.

Returns: an OK(0) status and index of the first trailing bit set to 1 or an error set to CCC_RESULT_FAIL if no 1 bit is found. Argument error is set if bitset is NULL.

◆ CCC_bitset_first_trailing_one_range()

CCC_Count CCC_bitset_first_trailing_one_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return the index of the first trailing bit set to 1 in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search.
[in]	range_bit_count	the size of the range to check.

Returns: an OK(0) status and the index of the first trailing bit set to 1 or CCC_RESULT_FAIL if no 1 bit is found. Argument error is returned bitset is NULL, or the range is invalid.

◆ CCC_bitset_first_trailing_ones()

CCC_Count CCC_bitset_first_trailing_ones	(	CCC_Bitset const *	bitset,
		size_t	ones_count
	)

Returns the index of the start of the first trailing number of contiguous 1 bits.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	ones_count	the number of trailing contiguous 1 bits to find.

Returns: an OK(0) status and the index in a search starting from the Least Significant Bit of the set of the first 1 in a sequence of bit_count 1 bits. If such a sequence cannot be found CCC_RESULT_FAIL result error is set. If bitset is NULL or bit_count is too large an argument error is set.

◆ CCC_bitset_first_trailing_ones_range()

CCC_Count CCC_bitset_first_trailing_ones_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count,
		size_t	ones_count
	)

Returns the index of the start of the first trailing number of contiguous 1 bits in the range [index, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search.
[in]	range_bit_count	the size of the range to check.
[in]	ones_count	the number of trailing contiguous 1 bits to find.

Returns: an OK(0) status and the starting index of the first 1 in a sequence of bit_count 1 bits. If no range is found CCC_RESULT_FAIL error is set. If bitset is NULL or arguments are out of range an argument error is set.

◆ CCC_bitset_first_trailing_zero()

CCC_Count CCC_bitset_first_trailing_zero ( CCC_Bitset const * bitset )

Return the index of the first bit set to 0 in the set.

Parameters

[in] bitset a pointer to the bit set.

Returns: an OK(0) status and the index of the first bit set to 0 or CCC_RESULT_FAIL if no 0 bit is found. If bitset is NULL an argument error is set.

◆ CCC_bitset_first_trailing_zero_range()

CCC_Count CCC_bitset_first_trailing_zero_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return the index of the first bit set to 0 in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search.
[in]	range_bit_count	the size of the range to check.

Returns: an OK(0) status and the index of the first bit set to 0 or CCC_RESULT_FAIL if no 0 bit is found. If bitset is NULL, or the range is invalid, an argument error is set.

◆ CCC_bitset_first_trailing_zeros()

CCC_Count CCC_bitset_first_trailing_zeros	(	CCC_Bitset const *	bitset,
		size_t	zeros_count
	)

Returns the index of the start of the first trailing number of contiguous 0 bits in the set.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	zeros_count	the number of trailing contiguous 0 bits to find.

Returns: an OK(0) status and the index in a search, starting from the Least Significant Bit of the set, of the first 0 in a sequence of zeros_count 0 bits. If such a sequence cannot be found CCC_RESULT_FAIL is returned. If bitset is NULL or num zeros is too large an argument error is set.

◆ CCC_bitset_first_trailing_zeros_range()

CCC_Count CCC_bitset_first_trailing_zeros_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count,
		size_t	zeros_count
	)

Returns the index of the start of the first trailing zeros_count contiguous 0 bits in the range [i, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to search.
[in]	range_bit_count	the size of the range to check.
[in]	zeros_count	the number of trailing contiguous 0 bits to find.

Returns: the index in a search, starting from the Least Significant Bit of the range, of the first 0 in a sequence of zeros_count 0 bits. If the input is invalid or such a sequence cannot be found CCC_RESULT_FAIL is returned.

◆ CCC_bitset_flip()

CCC_Tribool CCC_bitset_flip	(	CCC_Bitset *	bitset,
		size_t	index
	)

Toggle the bit at index i.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	index	the index identifying the bit to toggle

Returns: the state of the bit before the toggle operation, true if it was previously true, false if it was previously false, or error if bitset is NULL or index is out of range.

◆ CCC_bitset_flip_all()

CCC_Result CCC_bitset_flip_all ( CCC_Bitset * bitset )

Toggle all of the bits to their opposing boolean value.

Parameters

[in] bitset a pointer to the bit set.

Returns: the result of the operation. OK if successful, or an input error if bitset is NULL.

◆ CCC_bitset_flip_range()

CCC_Result CCC_bitset_flip_range	(	CCC_Bitset *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Flip all the bits in the range, starting at the Least Significant Bit in range and ending at the Most Significant Bit, to their opposite value.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to reset.
[in]	range_bit_count	the count of bits starting at index to reset.

Returns: the result of the operation. OK if successful, or an input error if bitset is NULL or the range is invalid by position, count, or both.

Note that a range is defined from index to index + count, where index + count is the exclusive end of the range. This is equivalent to moving from Least to Most Significant Bit in an integer.

◆ CCC_bitset_is_empty()

CCC_Tribool CCC_bitset_is_empty ( CCC_Bitset const * bitset )

Return true if no bits are actively tracked by the user and set.

Parameters

[in] bitset a pointer to the bit set.

Returns: CCC_TRUE if the size of the set is 0 meaning no bits, regardless of 0 or 1 status, are tracked by the set. CCC_TRIBOOL_ERROR is returned if bitset is NULL.

Warning: if the number of bits set to 1 is desired see CCC_bitset_popcount().

◆ CCC_bitset_is_equal()

CCC_Tribool CCC_bitset_is_equal	(	CCC_Bitset const *	left,
		CCC_Bitset const *	right
	)

Checks two bit sets of the same size (not capacity) for equality.

Parameters

[in]	left	pointer to a bit set.
[in]	right	pointer to another bit set of equal size.

Returns: true if the bit sets are of equal size with identical bit values at every position, false if the sets are different sizes or have mismatched bits. A bool error is returned if either pointer is NULL.

◆ CCC_bitset_is_proper_subset()

CCC_Tribool CCC_bitset_is_proper_subset	(	CCC_Bitset const *	subset,
		CCC_Bitset const *	set
	)

Return CCC_TRUE if subset is a proper subset of set (subset ⊂ set).

Parameters

[in]	subset	the subset to confirm as a proper subset of set.
[in]	set	the set to check subset against.

Returns: CCC_TRUE if all bit positions in subset share the same value–0 or 1–as the bit positions in set and set is of greater size than subset. A CCC_TRIBOOL_ERROR is returned if set or subset is NULL.

If set is of size 0 the function returns CCC_FALSE regardless of the size of subset. If set is not of size 0 and subset is of size 0 the function returns CCC_TRUE.

◆ CCC_bitset_is_subset()

CCC_Tribool CCC_bitset_is_subset	(	CCC_Bitset const *	subset,
		CCC_Bitset const *	set
	)

Return CCC_TRUE if subset is a subset of set (subset ⊆ set).

Parameters

[in]	subset	the subset to confirm as a subset of set.
[in]	set	the set to check subset against.

Returns: CCC_TRUE if all bit positions in subset share the same value–0 or 1–as the bit positions in set. A CCC_TRIBOOL_ERROR is returned if set or subset is NULL.

If set is size zero subset must also be of size 0 to return CCC_TRUE. If subset is size 0 the function returns CCC_TRUE regardless of the size of set.

◆ CCC_bitset_none()

CCC_Tribool CCC_bitset_none ( CCC_Bitset const * bitset )

Return true if all bits are set to 0.

Parameters

[in] bitset a pointer to the bit set.

Returns: CCC_TRUE if all bits are 0, CCC_FALSE if any bits are 1, CCC_TRIBOOL_ERROR if bitset is NULL.

◆ CCC_bitset_none_range()

CCC_Tribool CCC_bitset_none_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return true if all bits are 0 in the range [index, index + count).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting position.
[in]	range_bit_count	the size of the range to check.

Returns: CCC_TRUE if all bits are 0, CCC_FALSE if any bits are 1, CCC_TRIBOOL_ERROR if bitset is NULL, index is invalid, count is invalid, or both index and count are invalid.

◆ CCC_bitset_or()

CCC_Result CCC_bitset_or	(	CCC_Bitset *	destination,
		CCC_Bitset const *	source
	)

Bitwise OR destination set with source set.

Parameters

[in]	destination	the set to modified with the OR operation.
[in]	source	the set to be read as the source bits for the OR operation.

Returns: an OK result if the operation is successful or an input error if destination or source are NULL.

Note that sets are aligned from their Least Significant Bit and a smaller source set is conceptually padded with 0's in its higher order bits to align with the larger destination set (no modifications to the smaller set are performed to achieve this). This is done to stay consistent with how the operation would work on a smaller integer stored in a larger integer to align with the larger.

◆ CCC_bitset_pop_back()

CCC_Tribool CCC_bitset_pop_back ( CCC_Bitset * bitset )

Remove the Most Significant Bit from the set.

Parameters

[in] bitset a pointer to the bit set.

Returns: the previous value of the Most Significant Bit (CCC_TRUE or CCC_FALSE) or a bool error if bitset is NULL or bitset is empty.

◆ CCC_bitset_popcount()

CCC_Count CCC_bitset_popcount ( CCC_Bitset const * bitset )

Return the number of bits set to CCC_TRUE. O(n).

Parameters

[in] bitset a pointer to the bit set.

Returns: the total number of bits currently set to CCC_TRUE. CCC_RESULT_FAIL is returned if bitset is NULL.

◆ CCC_bitset_popcount_range()

CCC_Count CCC_bitset_popcount_range	(	CCC_Bitset const *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Return the number of bits set to CCC_TRUE in the range. O(n).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting position.
[in]	range_bit_count	the size of the range to check.

Returns: the total number of bits currently set in the range to CCC_TRUE. An argument error is set if bitset is NULL, index is invalid, count is invalid, or both index and count are invalid.

◆ CCC_bitset_push_back()

CCC_Result CCC_bitset_push_back	(	CCC_Bitset *	bitset,
		CCC_Tribool	bit,
		CCC_Allocator const *	allocator
	)

Append a bit value to the set as the new Most Significant Bit.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	bit	the value to push at the Most Significant Bit CCC_TRUE/CCC_FALSE.
[in]	allocator	the CCC_Allocator for possible resizing.

Returns: the result of the operation, ok if successful or an error if bad parameters are provided or resizing is required to accommodate a new bit but resizing fails.

◆ CCC_bitset_reserve()

CCC_Result CCC_bitset_reserve	(	CCC_Bitset *	bitset,
		size_t	to_add,
		CCC_Allocator const *	allocator
	)

Reserves space for at least to_add more bits.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	to_add	the number of elements to add to the current size.
[in]	allocator	the CCC_Allocator to use to reserve memory.

Returns: the result of the reservation. OK if successful, otherwise an error status is returned.

◆ CCC_bitset_reset()

CCC_Tribool CCC_bitset_reset	(	CCC_Bitset *	bitset,
		size_t	index
	)

Set the bit at valid index index to boolean value b (true or false).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	index	the valid index identifying the bit to set.

Returns: the state of the bit before the set operation, true if it was previously true, false if it was previously false, or error if bitset is NULL or index is out of range.

◆ CCC_bitset_reset_all()

CCC_Result CCC_bitset_reset_all ( CCC_Bitset * bitset )

Set all the bits to CCC_FALSE.

Parameters

[in] bitset a pointer to the bit set.

Returns: the result of the operation. OK if successful, or an input error if bitset is NULL.

◆ CCC_bitset_reset_range()

CCC_Result CCC_bitset_reset_range	(	CCC_Bitset *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count
	)

Set all the bits in the specified range starting at the Least Significant Bit of the range and ending at the Most Significant Bit of the range to CCC_FALSE.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to reset.
[in]	range_bit_count	the count of bits starting at index to reset.

Returns: the result of the operation. OK if successful, or an input error if bitset is NULL or the range is invalid by position, count, or both.

Note that a range is defined from [index, index + count). This is equivalent to moving from Least to Most Significant bit in an integer.

◆ CCC_bitset_set()

CCC_Tribool CCC_bitset_set	(	CCC_Bitset *	bitset,
		size_t	index,
		CCC_Tribool	bit
	)

Set the bit at valid index index to value bit (true or false).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	index	the valid index identifying the bit to set.
[in]	bit	the value to set at position index (CCC_TRUE or CCC_FALSE).

Returns: the state of the bit before the set operation, true if it was previously true, false if it was previously false, or error if bitset is NULL or index is out of range.

◆ CCC_bitset_set_all()

CCC_Result CCC_bitset_set_all	(	CCC_Bitset *	bitset,
		CCC_Tribool	bit
	)

Set all the bits to the provided value (CCC_TRUE or CCC_FALSE).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	bit	the value to set (CCC_TRUE or CCC_FALSE).

Returns: the result of the operation. OK if successful, or an input error if bitset is NULL.

◆ CCC_bitset_set_range()

CCC_Result CCC_bitset_set_range	(	CCC_Bitset *	bitset,
		size_t	range_start_index,
		size_t	range_bit_count,
		CCC_Tribool	bit
	)

Set all the bits in the specified range starting at the Least Significant Bit of the range and ending at the Most Significant Bit of the range (CCC_TRUE or CCC_FALSE).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	range_start_index	the starting index to set.
[in]	range_bit_count	the count of bits starting at index to set.
[in]	bit	the value to set (CCC_TRUE or CCC_FALSE).

Returns: the result of the operation. OK if successful, or an input error if bitset is NULL or the range is invalid by position, count, or both.

Note that a range is defined from [index, index + count). This is equivalent to moving from Least to Most Significant bit in an integer.

◆ CCC_bitset_shift_left()

CCC_Result CCC_bitset_shift_left	(	CCC_Bitset *	bitset,
		size_t	left_shifts
	)

Shift the bit set left by left_shifts amount.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	left_shifts	the number of left shifts to perform.

Returns: an ok result if the operation was successful or an error if the Bitset is NULL.

Note that if the number of shifts is greater than the bit set size the bit set is zeroed out rather than exhibiting undefined behavior as in the equivalent integer operation.

◆ CCC_bitset_shift_right()

CCC_Result CCC_bitset_shift_right	(	CCC_Bitset *	bitset,
		size_t	right_shifts
	)

Shift the bit set right by right_shifts amount.

Parameters

[in]	bitset	a pointer to the bit set.
[in]	right_shifts	the number of right shifts to perform.

Returns: an ok result if the operation was successful or an error if the Bitset is NULL.

Note that if the number of shifts is greater than the bit set size the bit set is zeroed out rather than exhibiting undefined behavior as in the equivalent integer operation.

◆ CCC_bitset_test()

CCC_Tribool CCC_bitset_test	(	CCC_Bitset const *	bitset,
		size_t	index
	)

Test the bit at index index for boolean status (CCC_TRUE or CCC_FALSE).

Parameters

[in]	bitset	a pointer to the bit set.
[in]	index	the index identifying the bit to set.

Returns: the state of the bit, or CCC_TRIBOOL_ERROR if bitset is NULL or index is out of range.

◆ CCC_bitset_xor()

CCC_Result CCC_bitset_xor	(	CCC_Bitset *	destination,
		CCC_Bitset const *	source
	)

Bitwise XOR destination set with source set.

Parameters

[in]	destination	the set to modified with the XOR operation.
[in]	source	the set to be read as the source bits for the XOR operation.

Returns: an OK result if the operation is successful or an input error if destination or source are NULL.

Note that sets are aligned from their Least Significant Bit and a smaller source set is conceptually padded with 0's in its higher order bits to align with the larger destination set (no modifications to the smaller set are performed to achieve this). This is done to stay consistent with how the operation would work on a smaller integer stored in a larger integer to align with the larger.

Detailed Description

Container Initialization

Container Types

Bit Membership Interface

Bit Modification Interface

Bit Scan Interface

Bit Operations Interface

Set Operations Interface

State Interface

Destructor Interface

Dynamic Interface

Macro Definition Documentation

◆ CCC_bitset_block_bytes

◆ CCC_bitset_block_count

◆ CCC_bitset_default

◆ CCC_bitset_for

◆ CCC_bitset_from

◆ CCC_bitset_storage_for

◆ CCC_bitset_with_capacity

◆ CCC_bitset_with_storage

Typedef Documentation

◆ CCC_Bit

◆ CCC_Bitset

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ CCC_bitset_all()

◆ CCC_bitset_all_range()

◆ CCC_bitset_and()

◆ CCC_bitset_any()

◆ CCC_bitset_any_range()

◆ CCC_bitset_blocks_capacity()

◆ CCC_bitset_blocks_count()

◆ CCC_bitset_capacity()

◆ CCC_bitset_clear()

◆ CCC_bitset_clear_and_free()

◆ CCC_bitset_copy()

◆ CCC_bitset_count()

◆ CCC_bitset_data()

◆ CCC_bitset_first_leading_one()

◆ CCC_bitset_first_leading_one_range()

◆ CCC_bitset_first_leading_ones()

◆ CCC_bitset_first_leading_ones_range()

◆ CCC_bitset_first_leading_zero()

◆ CCC_bitset_first_leading_zero_range()

◆ CCC_bitset_first_leading_zeros()

◆ CCC_bitset_first_leading_zeros_range()

◆ CCC_bitset_first_trailing_one()

◆ CCC_bitset_first_trailing_one_range()

◆ CCC_bitset_first_trailing_ones()

◆ CCC_bitset_first_trailing_ones_range()

◆ CCC_bitset_first_trailing_zero()

◆ CCC_bitset_first_trailing_zero_range()

◆ CCC_bitset_first_trailing_zeros()

◆ CCC_bitset_first_trailing_zeros_range()

◆ CCC_bitset_flip()

◆ CCC_bitset_flip_all()

◆ CCC_bitset_flip_range()

◆ CCC_bitset_is_empty()

◆ CCC_bitset_is_equal()

◆ CCC_bitset_is_proper_subset()

◆ CCC_bitset_is_subset()

◆ CCC_bitset_none()

◆ CCC_bitset_none_range()

◆ CCC_bitset_or()

◆ CCC_bitset_pop_back()

◆ CCC_bitset_popcount()

◆ CCC_bitset_popcount_range()

◆ CCC_bitset_push_back()

◆ CCC_bitset_reserve()

◆ CCC_bitset_reset()

◆ CCC_bitset_reset_all()

◆ CCC_bitset_reset_range()

◆ CCC_bitset_set()

◆ CCC_bitset_set_all()

◆ CCC_bitset_set_range()

◆ CCC_bitset_shift_left()

◆ CCC_bitset_shift_right()

◆ CCC_bitset_test()

◆ CCC_bitset_xor()