bit_buffer.h File Reference

Bit Buffer. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Typedefs
typedef struct BitBuffer	BitBuffer

Functions
BitBuffer *	bit_buffer_alloc (size_t capacity_bytes)
	Allocate a BitBuffer instance.
void	bit_buffer_free (BitBuffer *buf)
	Delete a BitBuffer instance.
void	bit_buffer_reset (BitBuffer *buf)
	Clear all data from a BitBuffer instance.
void	bit_buffer_copy (BitBuffer *buf, const BitBuffer *other)
	Copy another BitBuffer instance's contents to this one, replacing all of the original data.
void	bit_buffer_copy_right (BitBuffer *buf, const BitBuffer *other, size_t start_index)
	Copy all BitBuffer instance's contents to this one, starting from start_index, replacing all of the original data.
void	bit_buffer_copy_left (BitBuffer *buf, const BitBuffer *other, size_t end_index)
	Copy all BitBuffer instance's contents to this one, ending with end_index, replacing all of the original data.
void	bit_buffer_copy_bytes (BitBuffer *buf, const uint8_t *data, size_t size_bytes)
	Copy a byte array to a BitBuffer instance, replacing all of the original data.
void	bit_buffer_copy_bits (BitBuffer *buf, const uint8_t *data, size_t size_bits)
	Copy a byte array to a BitBuffer instance, replacing all of the original data.
void	bit_buffer_copy_bytes_with_parity (BitBuffer *buf, const uint8_t *data, size_t size_bits)
	Copy a byte with parity array to a BitBuffer instance, replacing all of the original data.
void	bit_buffer_write_bytes (const BitBuffer *buf, void *dest, size_t size_bytes)
	Write a BitBuffer instance's entire contents to an arbitrary memory location.
void	bit_buffer_write_bytes_with_parity (const BitBuffer *buf, void *dest, size_t size_bytes, size_t *bits_written)
	Write a BitBuffer instance's entire contents to an arbitrary memory location.
void	bit_buffer_write_bytes_mid (const BitBuffer *buf, void *dest, size_t start_index, size_t size_bytes)
	Write a slice of BitBuffer instance's contents to an arbitrary memory location.
bool	bit_buffer_has_partial_byte (const BitBuffer *buf)
	Check whether a BitBuffer instance contains a partial byte (i.e. the bit count is not divisible by 8).
bool	bit_buffer_starts_with_byte (const BitBuffer *buf, uint8_t byte)
	Check whether a BitBuffer instance's contents start with the designated byte.
size_t	bit_buffer_get_capacity_bytes (const BitBuffer *buf)
	Get a BitBuffer instance's capacity (i.e. the maximum possible amount of data), in bytes.
size_t	bit_buffer_get_size (const BitBuffer *buf)
	Get a BitBuffer instance's data size (i.e. the amount of stored data), in bits.
size_t	bit_buffer_get_size_bytes (const BitBuffer *buf)
	Get a BitBuffer instance's data size (i.e. the amount of stored data), in bytes.
uint8_t	bit_buffer_get_byte (const BitBuffer *buf, size_t index)
	Get a byte value at a specified index in a BitBuffer instance.
uint8_t	bit_buffer_get_byte_from_bit (const BitBuffer *buf, size_t index_bits)
	Get a byte value starting from the specified bit index in a BitBuffer instance.
const uint8_t *	bit_buffer_get_data (const BitBuffer *buf)
	Get the pointer to a BitBuffer instance's underlying data.
const uint8_t *	bit_buffer_get_parity (const BitBuffer *buf)
	Get the pointer to the parity data of a BitBuffer instance.
void	bit_buffer_set_byte (BitBuffer *buf, size_t index, uint8_t byte)
	Set byte value at a specified index in a BitBuffer instance.
void	bit_buffer_set_byte_with_parity (BitBuffer *buff, size_t index, uint8_t byte, bool parity)
	Set byte and parity bit value at a specified index in a BitBuffer instance.
void	bit_buffer_set_size (BitBuffer *buf, size_t new_size)
	Resize a BitBuffer instance to a new size, in bits.
void	bit_buffer_set_size_bytes (BitBuffer *buf, size_t new_size_bytes)
	Resize a BitBuffer instance to a new size, in bytes.
void	bit_buffer_append (BitBuffer *buf, const BitBuffer *other)
	Append all BitBuffer's instance contents to this one.
void	bit_buffer_append_right (BitBuffer *buf, const BitBuffer *other, size_t start_index)
	Append a BitBuffer's instance contents to this one, starting from start_index.
void	bit_buffer_append_byte (BitBuffer *buf, uint8_t byte)
	Append a byte to a BitBuffer instance.
void	bit_buffer_append_bytes (BitBuffer *buf, const uint8_t *data, size_t size_bytes)
	Append a byte array to a BitBuffer instance.
void	bit_buffer_append_bit (BitBuffer *buf, bool bit)
	Append a bit to a BitBuffer instance.

Detailed Description

Bit Buffer.

Various bits and bytes manipulation tools.

Function Documentation

bit_buffer_alloc()

BitBuffer * bit_buffer_alloc

(

size_t

capacity_bytes

)

Allocate a BitBuffer instance.

Parameters

[in]

capacity_bytes

maximum buffer capacity, in bytes

Returns

pointer to the allocated BitBuffer instance

bit_buffer_append()

void bit_buffer_append	(	BitBuffer *	buf,
		const BitBuffer *	other )

Append all BitBuffer's instance contents to this one.

Warning

The destination capacity must be no less than its original data size plus source data size.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be appended to
[in]	other	pointer to a BitBuffer instance to be appended

bit_buffer_append_bit()

void bit_buffer_append_bit	(	BitBuffer *	buf,
		bool	bit )

Append a bit to a BitBuffer instance.

Warning

The destination capacity must be sufficient to accommodate the additional bit.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be appended to
[in]	bit	bit value to be appended

bit_buffer_append_byte()

void bit_buffer_append_byte	(	BitBuffer *	buf,
		uint8_t	byte )

Append a byte to a BitBuffer instance.

Warning

The destination capacity must be no less its original data size plus one.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be appended to
[in]	byte	byte value to be appended

bit_buffer_append_bytes()

void bit_buffer_append_bytes	(	BitBuffer *	buf,
		const uint8_t *	data,
		size_t	size_bytes )

Append a byte array to a BitBuffer instance.

Warning

The destination capacity must be no less its original data size plus source data size.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be appended to
[in]	data	pointer to the byte array to be appended
[in]	size_bytes	size of the data to be appended, in bytes

bit_buffer_append_right()

void bit_buffer_append_right	(	BitBuffer *	buf,
		const BitBuffer *	other,
		size_t	start_index )

Append a BitBuffer's instance contents to this one, starting from start_index.

Warning

The destination capacity must be no less than the source data size counting from start_index.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be appended to
[in]	other	pointer to a BitBuffer instance to be appended
[in]	start_index	index to begin copying source data from

bit_buffer_copy()

void bit_buffer_copy	(	BitBuffer *	buf,
		const BitBuffer *	other )

Copy another BitBuffer instance's contents to this one, replacing all of the original data.

Warning

The destination capacity must be no less than the source data size.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to copy into
[in]	other	pointer to a BitBuffer instance to copy from

bit_buffer_copy_bits()

void bit_buffer_copy_bits	(	BitBuffer *	buf,
		const uint8_t *	data,
		size_t	size_bits )

Copy a byte array to a BitBuffer instance, replacing all of the original data.

Warning

The destination capacity must be no less than the source data size.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to copy into
[in]	data	pointer to the byte array to be copied
[in]	size_bits	size of the data to be copied, in bits

bit_buffer_copy_bytes()

void bit_buffer_copy_bytes	(	BitBuffer *	buf,
		const uint8_t *	data,
		size_t	size_bytes )

Copy a byte array to a BitBuffer instance, replacing all of the original data.

Warning

The destination capacity must be no less than the source data size.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to copy into
[in]	data	pointer to the byte array to be copied
[in]	size_bytes	size of the data to be copied, in bytes

bit_buffer_copy_bytes_with_parity()

void bit_buffer_copy_bytes_with_parity	(	BitBuffer *	buf,
		const uint8_t *	data,
		size_t	size_bits )

Copy a byte with parity array to a BitBuffer instance, replacing all of the original data.

Warning

The destination capacity must be no less than the source data size.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to copy into
[in]	data	pointer to the byte array to be copied
[in]	size_bits	size of the data to be copied, in bits

Note

Parity bits are placed starting with the most significant bit of each byte and moving up.

Example: DDDDDDDD PDDDDDDD DPDDDDDD DDP...

bit_buffer_copy_left()

void bit_buffer_copy_left	(	BitBuffer *	buf,
		const BitBuffer *	other,
		size_t	end_index )

Copy all BitBuffer instance's contents to this one, ending with end_index, replacing all of the original data.

Warning

The destination capacity must be no less than the source data size counting to end_index.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to copy into
[in]	other	pointer to a BitBuffer instance to copy from
[in]	end_index	index to end copying source data at

bit_buffer_copy_right()

void bit_buffer_copy_right	(	BitBuffer *	buf,
		const BitBuffer *	other,
		size_t	start_index )

Copy all BitBuffer instance's contents to this one, starting from start_index, replacing all of the original data.

Warning

The destination capacity must be no less than the source data size counting from start_index.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to copy into
[in]	other	pointer to a BitBuffer instance to copy from
[in]	start_index	index to begin copying source data from

bit_buffer_free()

void bit_buffer_free

(

BitBuffer *

buf

)

Delete a BitBuffer instance.

Parameters

[in,out]

buf

pointer to a BitBuffer instance

bit_buffer_get_byte()

uint8_t bit_buffer_get_byte	(	const BitBuffer *	buf,
		size_t	index )

Get a byte value at a specified index in a BitBuffer instance.

Warning

The index must be valid (i.e. less than the instance's data size in bytes).

Parameters

[in]	buf	pointer to a BitBuffer instance to be queried
[in]	index	index of the byte in question

Returns

byte value

bit_buffer_get_byte_from_bit()

uint8_t bit_buffer_get_byte_from_bit	(	const BitBuffer *	buf,
		size_t	index_bits )

Get a byte value starting from the specified bit index in a BitBuffer instance.

Warning

The resulting byte might correspond to a single byte (if the index is a multiple of 8), or two overlapping bytes combined. The index must be valid (i.e. less than the instance's data size in bits).

Parameters

[in]	buf	pointer to a BitBuffer instance to be queried
[in]	index_bits	bit index of the byte in question

Returns

byte value

bit_buffer_get_capacity_bytes()

size_t bit_buffer_get_capacity_bytes

(

const BitBuffer *

buf

)

Get a BitBuffer instance's capacity (i.e. the maximum possible amount of data), in bytes.

Parameters

[in]

buf

pointer to a BitBuffer instance to be queried

Returns

capacity, in bytes

bit_buffer_get_data()

const uint8_t * bit_buffer_get_data

(

const BitBuffer *

buf

)

Get the pointer to a BitBuffer instance's underlying data.

Parameters

[in]

buf

pointer to a BitBuffer instance to be queried

Returns

pointer to the underlying data

bit_buffer_get_parity()

const uint8_t * bit_buffer_get_parity

(

const BitBuffer *

buf

)

Get the pointer to the parity data of a BitBuffer instance.

Parameters

[in]

buf

pointer to a BitBuffer instance to be queried

Returns

pointer to the parity data

bit_buffer_get_size()

size_t bit_buffer_get_size

(

const BitBuffer *

buf

)

Get a BitBuffer instance's data size (i.e. the amount of stored data), in bits.

Warning

Might be not divisible by 8 (see bit_buffer_is_partial_byte).

Parameters

[in]

buf

pointer to a BitBuffer instance to be queried

Returns

data size, in bits.

bit_buffer_get_size_bytes()

size_t bit_buffer_get_size_bytes

(

const BitBuffer *

buf

)

Get a BitBuffer instance's data size (i.e. the amount of stored data), in bytes.

Warning

If a partial byte is present, it is also counted.

Parameters

[in]

buf

pointer to a BitBuffer instance to be queried

Returns

data size, in bytes.

bit_buffer_has_partial_byte()

bool bit_buffer_has_partial_byte

(

const BitBuffer *

buf

)

Check whether a BitBuffer instance contains a partial byte (i.e. the bit count is not divisible by 8).

Parameters

[in]

buf

pointer to a BitBuffer instance to be checked

Returns

true if the instance contains a partial byte, false otherwise

bit_buffer_reset()

void bit_buffer_reset

(

BitBuffer *

buf

)

Clear all data from a BitBuffer instance.

Parameters

[in,out]

buf

pointer to a BitBuffer instance

bit_buffer_set_byte()

void bit_buffer_set_byte	(	BitBuffer *	buf,
		size_t	index,
		uint8_t	byte )

Set byte value at a specified index in a BitBuffer instance.

Warning

The index must be valid (i.e. less than the instance's data size in bytes).

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be modified
[in]	index	index of the byte in question
[in]	byte	byte value to be set at index

bit_buffer_set_byte_with_parity()

void bit_buffer_set_byte_with_parity	(	BitBuffer *	buff,
		size_t	index,
		uint8_t	byte,
		bool	parity )

Set byte and parity bit value at a specified index in a BitBuffer instance.

Warning

The index must be valid (i.e. less than the instance's data size in bytes).

Parameters

[in,out]	buff	pointer to a BitBuffer instance to be modified
[in]	index	index of the byte in question
[in]	byte	byte value to be set at index
[in]	parity	parity bit value to be set at index

bit_buffer_set_size()

void bit_buffer_set_size	(	BitBuffer *	buf,
		size_t	new_size )

Resize a BitBuffer instance to a new size, in bits.

Warning

May cause bugs. Use only if absolutely necessary.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be resized
[in]	new_size	the new size of the buffer, in bits

bit_buffer_set_size_bytes()

void bit_buffer_set_size_bytes	(	BitBuffer *	buf,
		size_t	new_size_bytes )

Resize a BitBuffer instance to a new size, in bytes.

Warning

May cause bugs. Use only if absolutely necessary.

Parameters

[in,out]	buf	pointer to a BitBuffer instance to be resized
[in]	new_size_bytes	the new size of the buffer, in bytes

bit_buffer_starts_with_byte()

bool bit_buffer_starts_with_byte	(	const BitBuffer *	buf,
		uint8_t	byte )

Check whether a BitBuffer instance's contents start with the designated byte.

Parameters

[in]	buf	pointer to a BitBuffer instance to be checked
[in]	byte	byte value to be checked against

Returns

true if data starts with designated byte, false otherwise

bit_buffer_write_bytes()

void bit_buffer_write_bytes	(	const BitBuffer *	buf,
		void *	dest,
		size_t	size_bytes )

Write a BitBuffer instance's entire contents to an arbitrary memory location.

Warning

The destination memory must be allocated. Additionally, the destination capacity must be no less than the source data size.

Parameters

[in]	buf	pointer to a BitBuffer instance to write from
[out]	dest	pointer to the destination memory location
[in]	size_bytes	maximum destination data size, in bytes

bit_buffer_write_bytes_mid()

void bit_buffer_write_bytes_mid	(	const BitBuffer *	buf,
		void *	dest,
		size_t	start_index,
		size_t	size_bytes )

Write a slice of BitBuffer instance's contents to an arbitrary memory location.

Warning

The destination memory must be allocated. Additionally, the destination capacity must be no less than the requested slice size.

Parameters

[in]	buf	pointer to a BitBuffer instance to write from
[out]	dest	pointer to the destination memory location
[in]	start_index	index to begin copying source data from
[in]	size_bytes	data slice size, in bytes

bit_buffer_write_bytes_with_parity()

void bit_buffer_write_bytes_with_parity	(	const BitBuffer *	buf,
		void *	dest,
		size_t	size_bytes,
		size_t *	bits_written )

Write a BitBuffer instance's entire contents to an arbitrary memory location.

Additionally, place a parity bit after each byte.

Warning

The destination memory must be allocated. Additionally, the destination capacity must be no less than the source data size plus parity.

Parameters

[in]	buf	pointer to a BitBuffer instance to write from
[out]	dest	pointer to the destination memory location
[in]	size_bytes	maximum destination data size, in bytes
[out]	bits_written	actual number of bits written, in bits

Note

Parity bits are placed starting with the most significant bit of each byte and moving up.

Example: DDDDDDDD PDDDDDDD DPDDDDDD DDP...