Bitwise flags parser and generator

Data Structures
struct	M_bitlist_t

Enumerations
enum	M_bitlist_flags_t {   M_BITLIST_FLAG_NONE = 0 ,   M_BITLIST_FLAG_DONT_TRIM_WHITESPACE = 1<<0 ,   M_BITLIST_FLAG_CASE_SENSITIVE = 1<<1 ,   M_BITLIST_FLAG_IGNORE_DUPLICATE_ID = 1<<2 ,   M_BITLIST_FLAG_IGNORE_UNKNOWN = 1<<3 ,   M_BITLIST_FLAG_DONT_REQUIRE_POWEROF2 = 1<<4 }

Functions
M_bool	M_bitlist_list (char **out, M_bitlist_flags_t flags, const M_bitlist_t *list, M_uint64 bits, unsigned char delim, char *error, size_t error_len)
M_bool	M_bitlist_parse (M_uint64 *out, M_bitlist_flags_t flags, const M_bitlist_t *list, const char *data, unsigned char delim, char *error, size_t error_len)
M_bool	M_bitlist_tohash (M_hash_stru64_t **hash_toint, M_hash_u64str_t **hash_tostr, M_bitlist_flags_t flags, const M_bitlist_t *list, char *error, size_t error_len)
M_bool	M_bitlist_hash_parse (M_uint64 *out, M_bitlist_flags_t flags, const M_hash_stru64_t *hash_toint, const char *data, unsigned char delim, char *error, size_t error_len)
const char *	M_bitlist_single_tostr (const M_bitlist_t *list, M_uint64 id)
M_uint64	M_bitlist_single_toint (const M_bitlist_t *list, const char *name)

Detailed Description

Allows for easy creation of a data structure to parse and generate human readable flags lists made up of bits.

static const M_bitlist_t myflags[] = {
  { 1 << 0, "flag1" },
  { 1 << 1, "flag2" },
  { 1 << 2, "flag3" },
  { 0,      NULL    }
};
 
M_uint64  initial_flags = (1<<0) | (1<<2);
char     *human_flags   = NULL;
M_uint64  final_flags   = 0;
M_bool    rv            = M_FALSE;
 
if (!M_bitlist_list(&human_flags, M_BITLIST_FLAG_NONE, myflags, initial_flags, '|', error, sizeof(error)))
  goto fail;
 
if (!M_bitlist_parse(&final_flags, M_BITLIST_FLAG_NONE, myflags, human_flags, '|', error, sizeof(error)))
  goto fail;
 
if (initial_flags != final_flags) {
  M_snprintf(error, sizeof(error), "initial flags don't match converted");
  goto fail;
}
rv = M_TRUE;
 
fail:
M_free(human_flags);
if (!rv) {
  M_printf("FAILURE: %s", error);
}

---

Data Structure Documentation

M_bitlist_t

struct M_bitlist_t

Data structure to be created as an array and filled in by caller. Must be terminated by an entry where the name parameter is set to NULL

Data Fields
M_uint64	id	The bit to set, usually a power of 2
const char *	name	Human-readable name associated with the flag/bit

Enumeration Type Documentation

M_bitlist_flags_t

enum M_bitlist_flags_t

Flags that may be passed on to the parser or human-readable generator

Enumerator
M_BITLIST_FLAG_NONE	No Flags
M_BITLIST_FLAG_DONT_TRIM_WHITESPACE	Parse only. Don't trim whitespace that might surround flags.
M_BITLIST_FLAG_CASE_SENSITIVE	Parse only. Case sensitive flag matching.
M_BITLIST_FLAG_IGNORE_DUPLICATE_ID	Ignore duplicate ids. May be used for aliases. First value in list with ID will be used
M_BITLIST_FLAG_IGNORE_UNKNOWN	If a bit is set that is not known, ignore
M_BITLIST_FLAG_DONT_REQUIRE_POWEROF2	Don't require a field to be a power of 2.

Function Documentation

M_bitlist_list()

M_bool M_bitlist_list	(	char **	out,
		M_bitlist_flags_t	flags,
		const M_bitlist_t *	list,
		M_uint64	bits,
		unsigned char	delim,
		char *	error,
		size_t	error_len
	)

Generate a human-readable list from the array provided and bits provided, delimited by the specified delimiter. Note that there is not a 'hash' version of this function as it would likely be less efficient and would also not support the ability to handle aggregate entries that might contain more than 1 bit set.

Parameters

[out]	out	Null-terminated string representing the human-readable bit list
[in]	flags	Flags used when generating the list or determining errors
[in]	list	Array passed in defining all bits to human-readable
[in]	bits	Machine-readable bits passed in to be converted
[in]	delim	Delimiter for human-readable list output
[in,out]	error	Buffer to hold error string.
[in]	error_len	Length of error buffer

Returns

M_TRUE on success, M_FALSE on failure

M_bitlist_parse()

M_bool M_bitlist_parse	(	M_uint64 *	out,
		M_bitlist_flags_t	flags,
		const M_bitlist_t *	list,
		const char *	data,
		unsigned char	delim,
		char *	error,
		size_t	error_len
	)

Generate an integer after parsing the provided human-readable string of bits/flags.

Parameters

[out]	out	64bit integer of set bits
[in]	flags	Flags used when parsing the provided human-readable string
[in]	list	Array passed in defining all bits to human-readable name
[in]	data	Human-readable bits/flags in null terminated string form
[in]	delim	Delimiter for human-readable list input
[in,out]	error	Buffer to hold error string.
[in]	error_len	Length of error buffer

Returns

M_TRUE on success, M_FALSE on failure

M_bitlist_tohash()

M_bool M_bitlist_tohash	(	M_hash_stru64_t **	hash_toint,
		M_hash_u64str_t **	hash_tostr,
		M_bitlist_flags_t	flags,
		const M_bitlist_t *	list,
		char *	error,
		size_t	error_len
	)

Convert a bitlist into hash implementations for more efficient lookups.

Parameters

[out]	hash_toint	Hashtable for conversion from string to integer.
[out]	hash_tostr	Hashtable for conversion from integer to string.
[in]	flags	Flags used when generating the list or determining errors.
[in]	list	Array passed in defining all bits to human-readable name
[in,out]	error	Buffer to hold error string.
[in]	error_len	Length of error buffer

Returns

M_TRUE on success, M_FALSE on failure

M_bitlist_hash_parse()

M_bool M_bitlist_hash_parse	(	M_uint64 *	out,
		M_bitlist_flags_t	flags,
		const M_hash_stru64_t *	hash_toint,
		const char *	data,
		unsigned char	delim,
		char *	error,
		size_t	error_len
	)

Generate an integer after parsing the provided human-readable string of bits/flags.

Parameters

[out]	out	64bit integer of set bits
[in]	flags	Flags used when parsing the provided human-readable string
[in]	hash_toint	hash_toint returned from M_bitlist_tohash() with appropriate list.
[in]	data	Human-readable bits/flags in null terminated string form
[in]	delim	Delimiter for human-readable list input
[in,out]	error	Buffer to hold error string.
[in]	error_len	Length of error buffer

Returns

M_TRUE on success, M_FALSE on failure

M_bitlist_single_tostr()

const char * M_bitlist_single_tostr	(	const M_bitlist_t *	list,
		M_uint64	id
	)

Extract a single name from a bitlist that exactly matches the passed in id.

Parameters

[in]	list	Array passed in defining all bits to human-readable name
[in]	id	ID to match

Returns

NULL if not found, otherwise pointer to name in bitlist

M_bitlist_single_toint()

M_uint64 M_bitlist_single_toint	(	const M_bitlist_t *	list,
		const char *	name
	)

Extract a single id from a bitlist that exactly matches the passed in name.

Parameters

[in]	list	Array passed in defining all bits to human-readable name
[in]	name	name to match

Returns

0 if not found, otherwise id of name in bitlist