Typedefs
typedef struct M_hash_dict	M_hash_dict_t

typedef struct M_hash_dict_enum	M_hash_dict_enum_t

Enumerations
enum	M_hash_dict_flags_t { M_HASH_DICT_NONE = 0 , M_HASH_DICT_CASECMP = 1 << 0 , M_HASH_DICT_KEYS_UPPER = 1 << 1 , M_HASH_DICT_KEYS_LOWER = 1 << 2 , M_HASH_DICT_KEYS_ORDERED = 1 << 3 , M_HASH_DICT_KEYS_SORTASC = 1 << 4 , M_HASH_DICT_KEYS_SORTDESC = 1 << 5 , M_HASH_DICT_MULTI_VALUE = 1 << 6 , M_HASH_DICT_MULTI_SORTASC = 1 << 7 , M_HASH_DICT_MULTI_SORTDESC = 1 << 8 , M_HASH_DICT_MULTI_GETLAST = 1 << 9 , M_HASH_DICT_MULTI_CASECMP = 1 << 10 , M_HASH_DICT_STATIC_SEED = 1 << 11 , M_HASH_DICT_DESER_TRIM_WHITESPACE = 1 << 26 }

enum	M_hash_dict_ser_flag_t { M_HASH_DICT_SER_FLAG_NONE = 0 , M_HASH_DICT_SER_FLAG_ALWAYS_QUOTE = 1 << 0 , M_HASH_DICT_SER_FLAG_QUOTE_NON_ANS = 1 << 1 , M_HASH_DICT_SER_FLAG_HEXENCODE_NONPRINT = 1 << 2 , M_HASH_DICT_SER_FLAG_LF_TO_CRLF = 1 << 3 }

Functions
M_hash_dict_t *	M_hash_dict_create (size_t size, M_uint8 fillpct, M_uint32 flags) M_MALLOC

void	M_hash_dict_destroy (M_hash_dict_t *h) M_FREE(1)

M_bool	M_hash_dict_insert (M_hash_dict_t h, const char key, const char *value)

M_bool	M_hash_dict_remove (M_hash_dict_t h, const char key)

M_bool	M_hash_dict_get (const M_hash_dict_t h, const char key, const char **value)

const char *	M_hash_dict_get_direct (const M_hash_dict_t h, const char key)

const char *	M_hash_dict_get_direct_default (const M_hash_dict_t h, const char key, const char *def)

M_bool	M_hash_dict_is_multi (const M_hash_dict_t *h)

M_bool	M_hash_dict_multi_len (const M_hash_dict_t h, const char key, size_t *len)

M_bool	M_hash_dict_multi_get (const M_hash_dict_t h, const char key, size_t idx, const char **value)

const char *	M_hash_dict_multi_get_direct (const M_hash_dict_t h, const char key, size_t idx)

M_bool	M_hash_dict_multi_remove (M_hash_dict_t h, const char key, size_t idx)

M_uint32	M_hash_dict_size (const M_hash_dict_t *h)

size_t	M_hash_dict_num_collisions (const M_hash_dict_t *h)

size_t	M_hash_dict_num_expansions (const M_hash_dict_t *h)

size_t	M_hash_dict_num_keys (const M_hash_dict_t *h)

size_t	M_hash_dict_enumerate (const M_hash_dict_t h, M_hash_dict_enum_t *hashenum)

M_bool	M_hash_dict_enumerate_next (const M_hash_dict_t h, M_hash_dict_enum_t hashenum, const char key, const char value)

void	M_hash_dict_enumerate_free (M_hash_dict_enum_t *hashenum)

void	M_hash_dict_merge (M_hash_dict_t *dest, M_hash_dict_t src) M_FREE(2)

M_hash_dict_t *	M_hash_dict_duplicate (const M_hash_dict_t *h) M_MALLOC

M_bool	M_hash_dict_serialize_buf (const M_hash_dict_t dict, M_buf_t buf, char delim, char kv_delim, char quote, char escape, M_uint32 flags)

char *	M_hash_dict_serialize (const M_hash_dict_t *dict, char delim, char kv_delim, char quote, char escape, M_uint32 flags)

M_hash_dict_t *	M_hash_dict_deserialize (const char *str, size_t len, char delim, char kv_delim, char quote, char escape, M_uint32 flags)

Detailed Description

Hashtable, meant for storing string key/value pairs.

References to the data will always be read-only. All keys and values will be duplicated by the hashtable.

Typedef Documentation

◆ M_hash_dict_t

typedef struct M_hash_dict M_hash_dict_t

◆ M_hash_dict_enum_t

typedef struct M_hash_dict_enum M_hash_dict_enum_t

Enumeration Type Documentation

◆ M_hash_dict_flags_t

enum M_hash_dict_flags_t

Flags for controlling the behavior of the hashtable.

Enumerator
M_HASH_DICT_NONE	Case sensitive single value (new values replace).
M_HASH_DICT_CASECMP	Key compare is case insensitive.
M_HASH_DICT_KEYS_UPPER	Keys will be upper cased before being inserted. Should be used in conjunction with M_HASH_DICT_CASECMP.
M_HASH_DICT_KEYS_LOWER	Keys will be lower cased before being inserted. Should be used in conjunction with M_HASH_DICT_CASECMP.
M_HASH_DICT_KEYS_ORDERED	Keys should be ordered. Default is insertion order unless the sorted option is specified.
M_HASH_DICT_KEYS_SORTASC	When the keys are ordered sort them using the key_equality function.
M_HASH_DICT_KEYS_SORTDESC	When the keys are ordered sort them using the key_equality function.
M_HASH_DICT_MULTI_VALUE	Allow keys to contain multiple values. Sorted in insertion order another sorting is specified.
M_HASH_DICT_MULTI_SORTASC	Allow keys to contain multiple values sorted in ascending order
M_HASH_DICT_MULTI_SORTDESC	Allow keys to contain multiple values sorted in descending order
M_HASH_DICT_MULTI_GETLAST	When using get and get_direct function get the last value from the list when allowing multiple values. The default is to get the first value.
M_HASH_DICT_MULTI_CASECMP	Value compare is case insensitive.
M_HASH_DICT_STATIC_SEED	Use a static seed for hash function initialization. This greatly reduces the security of the hashtable and removes collision attack protections. This should only be used as a performance optimization when creating millions of hashtables with static data specifically for quick look up. DO NOT use this flag with any hashtable that could store user generated data! Be very careful about duplicating a hashtable that was created with this flag. All duplicates will use the static seed.
M_HASH_DICT_DESER_TRIM_WHITESPACE	During deserialization, trim whitespace.

◆ M_hash_dict_ser_flag_t

enum M_hash_dict_ser_flag_t

Possible flags for M_hash_dict_serialize()

Enumerator
M_HASH_DICT_SER_FLAG_NONE	Default flags
M_HASH_DICT_SER_FLAG_ALWAYS_QUOTE	Always quote the value even if not necessary. Cannot be used with M_HASH_DICT_SER_FLAG_QUOTE_NON_ANS
M_HASH_DICT_SER_FLAG_QUOTE_NON_ANS	Quote any string that contains non Alpha-numeric or single space (0x20). Cannot be used with M_HASH_DICT_SER_FLAG_ALWAYS_QUOTE
M_HASH_DICT_SER_FLAG_HEXENCODE_NONPRINT	Any non-printable characters should be hex-encoded as [%02X] in the resulting output string
M_HASH_DICT_SER_FLAG_LF_TO_CRLF	If a separator is specified as LF ' ', convert it to CRLF `\r\n`. Necessary since delimiters can only be a single character.

Function Documentation

◆ M_hash_dict_create()

M_hash_dict_t * M_hash_dict_create	(	size_t	size,
		M_uint8	fillpct,
		M_uint32	flags
	)

Create a new hashtable.

The hashtable will pre-allocate an array of buckets based on the rounded up size specified. Any hash collisions will result in those collisions being chained together via a linked list. The hashtable will auto-expand by a power of 2 when the fill percentage specified is reached. All key entries are compared in a case-insensitive fashion, and are duplicated internally. Values are duplicated. Case is preserved for both keys and values.

Parameters

[in]	size	Size of the hash table. If not specified as a power of 2, will be rounded up to the nearest power of 2.
[in]	fillpct	The maximum fill percentage before the hash table is expanded. If 0 is specified, the hashtable will never expand, otherwise the value must be between 1 and 99 (recommended: 75).
[in]	flags	M_hash_dict_flags_t flags for modifying behavior.

Returns: Allocated hashtable.

See also: M_hash_dict_destroy

◆ M_hash_dict_destroy()

void M_hash_dict_destroy ( M_hash_dict_t * h )

Destroy the hashtable.

Parameters

[in] h Hashtable to destroy

◆ M_hash_dict_insert()

M_bool M_hash_dict_insert	(	M_hash_dict_t *	h,
		const char *	key,
		const char *	value
	)

Insert an entry into the hashtable.

If this is a multi-value dictionary (

See also: M_HASH_DICT_MULTI_VALUE) and an entry already exists under the given key, the new value is added onto the end of the list. Otherwise, the new value replaces any previous value stored under the given key.

Parameters

[in,out]	h	Hashtable being referenced.
[in]	key	Key to insert. A NULL or empty string is explicity disallowed.
[in]	value	Value to insert into hashtable. Value will be duplicated, and case will be preserved. May be NULL.

Returns: M_TRUE on success, or M_FALSE on failure.

◆ M_hash_dict_remove()

M_bool M_hash_dict_remove	(	M_hash_dict_t *	h,
		const char *	key
	)

Remove an entry from the hashtable.

Parameters

[in,out]	h	Hashtable being referenced.
[in]	key	Key to remove from the hashtable. A NULL or empty string is explicitly disallowed.

Returns: M_TRUE on success, or M_FALSE if key does not exist.

◆ M_hash_dict_get()

M_bool M_hash_dict_get	(	const M_hash_dict_t *	h,
		const char *	key,
		const char **	value
	)

Retrieve the value for a key from the hashtable.

Parameters

[in]	h	Hashtable being referenced.
[in]	key	Key for value. A NULL or empty string is explicitly disallowed.
[out]	value	Pointer to value stored in the hashtable. Optional, pass NULL if not needed.

Returns: M_TRUE if value retrieved, M_FALSE if key does not exist.

◆ M_hash_dict_get_direct()

const char * M_hash_dict_get_direct	(	const M_hash_dict_t *	h,
		const char *	key
	)

Retrieve the value for a key from the hashtable, and return it directly as the return value.

This cannot be used if you need to differentiate between a key that doesn't exist vs a key with a NULL value.

Parameters

[in]	h	Hashtable being referenced.
[in]	key	Key for value to retrieve from the hashtable. A NULL or empty string is explicitly disallowed.

Returns: NULL if key doesn't exist or NULL value on file, otherwise the value.

◆ M_hash_dict_get_direct_default()

const char * M_hash_dict_get_direct_default	(	const M_hash_dict_t *	h,
		const char *	key,
		const char *	def
	)

Retrieve the value for a key from the hashtable, and return it directly as the return value.

If the key does not exist or the value is NULL the provided default value will be returned.

Parameters

[in]	h	Hashtable being referenced.
[in]	key	Key for value to retrieve from the hashtable. A NULL or empty string is explicitly disallowed.
[in]	def	A default value.

Returns: def if key doesn't exist or NULL value on file, otherwise the value.

◆ M_hash_dict_is_multi()

M_bool M_hash_dict_is_multi ( const M_hash_dict_t * h )

Wether the hashtable a multi value table.

Parameters

[in] h Hashtable being referenced.

Returns: M_TRUE if a multi value hashtable.

◆ M_hash_dict_multi_len()

M_bool M_hash_dict_multi_len	(	const M_hash_dict_t *	h,
		const char *	key,
		size_t *	len
	)

Get the number of values for a given key.

Parameters

[in]	h	Hashtable being referenced.
[in]	key	Key for value to retrieve.
[out]	len	The number of values.

Returns: M_TRUE if length is retrieved, M_FALSE if key does not exist.

◆ M_hash_dict_multi_get()

M_bool M_hash_dict_multi_get	(	const M_hash_dict_t *	h,
		const char *	key,
		size_t	idx,
		const char **	value
	)

Retrieve the value for a key from the given index when supporting muli-values.

Parameters

[in]	h	Hashtable being referenced.
[in]	key	Key for value to retrieve.
[in]	idx	The index the value resides at.
[out]	value	Pointer to value stored. Optional, pass NULL if not needed.

Returns: M_TRUE if value retrieved, M_FALSE if key does not exist

◆ M_hash_dict_multi_get_direct()

const char * M_hash_dict_multi_get_direct	(	const M_hash_dict_t *	h,
		const char *	key,
		size_t	idx
	)

Retrieve the value for a key from the given index when supporting muli-values.

Parameters

[in]	h	Hashtable being referenced.
[in]	key	Key for value to retrieve.
[in]	idx	The index the value resides at.

Returns: M_TRUE if value retrieved, M_FALSE if key does not exist.

◆ M_hash_dict_multi_remove()

M_bool M_hash_dict_multi_remove	(	M_hash_dict_t *	h,
		const char *	key,
		size_t	idx
	)

Remove a value from the hashtable when supporting muli-values.

If all values have been removed then the key will be removed.

Parameters

[in,out]	h	Hashtable being referenced
[in]	key	Key for value to retrieve.
[in]	idx	The index the value resides at.

Returns: M_TRUE if the value was removed, M_FALSE if key does not exist.

◆ M_hash_dict_size()

M_uint32 M_hash_dict_size ( const M_hash_dict_t * h )

Retrieve the current size (number of buckets/slots, not necessarily used).

Parameters

[in] h Hashtable being referenced.

Returns: Size of the hashtable

◆ M_hash_dict_num_collisions()

size_t M_hash_dict_num_collisions ( const M_hash_dict_t * h )

Retrieve the number of collisions for hashtable entries that has occurred since creation.

Parameters

[in] h Hashtable being referenced.

Returns: Number of collisions.

◆ M_hash_dict_num_expansions()

size_t M_hash_dict_num_expansions ( const M_hash_dict_t * h )

Retrieve the number of expansions/rehashes since creation.

Parameters

[in] h Hashtable being referenced.

Returns: number of expansions/rehashes.

◆ M_hash_dict_num_keys()

size_t M_hash_dict_num_keys ( const M_hash_dict_t * h )

Retrieve the number of entries in the hashtable.

This is the number of keys stored.

Parameters

[in] h Hashtable being referenced.

Returns: number of entries in the hashtable.

◆ M_hash_dict_enumerate()

size_t M_hash_dict_enumerate	(	const M_hash_dict_t *	h,
		M_hash_dict_enum_t **	hashenum
	)

Start an enumeration of the keys within a hashtable.

Parameters

[in]	h	Hashtable being referenced.
[out]	hashenum	Outputs an initialized state variable for starting an enumeration.

Returns: Number of items in the hashtable

See also: M_hash_dict_enumerate_free

◆ M_hash_dict_enumerate_next()

M_bool M_hash_dict_enumerate_next	(	const M_hash_dict_t *	h,
		M_hash_dict_enum_t *	hashenum,
		const char **	key,
		const char **	value
	)

Retrieve the next item from a hashtable enumeration.

If multi-value, keys will appear multiple times as each value will be retrieved individually.

Parameters

[in]	h	Hashtable being referenced.
[in,out]	hashenum	State variable for tracking the enumeration process.
[out]	key	Value of next enumerated key. Optional, pass NULL if not needed.
[out]	value	Value of next enumerated value. Optional, pass NULL if not needed.

Returns: M_TRUE if enumeration succeeded, M_FALSE if no more keys.

◆ M_hash_dict_enumerate_free()

void M_hash_dict_enumerate_free ( M_hash_dict_enum_t * hashenum )

Destroy an enumeration state.

Parameters

[in] hashenum Enumeration to destroy.

◆ M_hash_dict_merge()

void M_hash_dict_merge	(	M_hash_dict_t **	dest,
		M_hash_dict_t *	src
	)

Merge two hashtables together.

The second (src) hashtable will be destroyed automatically upon completion of this function. Any key/value pointers for the hashtable will be directly copied over to the destination hashtable, they will not be duplicated. Any keys which exist in 'dest' that also exist in 'src' will be overwritten by the 'src' value.

If dest and src are multi-value, all values from src will be copied into dest and the values from dest will not be removed. If dest is not multi-value and src is, then only the last value in src will be present in dest. If dest is multi-value and src is not, then the value from src will be added to dest.

Parameters

[in,out]	dest	Pointer by reference to the hashtable receiving the key/value pairs. if dest is NULL, the src address will simply be copied to dest.
[in,out]	src	Pointer to the hashtable giving up its key/value pairs.

◆ M_hash_dict_duplicate()

M_hash_dict_t * M_hash_dict_duplicate ( const M_hash_dict_t * h )

Duplicate an existing hashtable.

Copying all keys and values.

Parameters

[in] h Hashtable to be copied.

Returns: Duplicated hashtable.

◆ M_hash_dict_serialize_buf()

M_bool M_hash_dict_serialize_buf	(	const M_hash_dict_t *	dict,
		M_buf_t *	buf,
		char	delim,
		char	kv_delim,
		char	quote,
		char	escape,
		M_uint32	flags
	)

Serialize a dictionary and write it to the provided M_buf_t.

Parameters

[in]	dict	Dictionary to serialize
[in]	buf	Destination buffer to write to, already initialized.
[in]	delim	Delimiter between key/value pairs (recommended ';')
[in]	kv_delim	Delimiter between the key and value (recommended '=')
[in]	quote	Quote character (recommended '"')
[in]	escape	Escape character (recommended '\' or '"')
[in]	flags	Bitmap of possible M_hash_dict_ser_flag_t flags

Returns: M_TRUE on success or M_FALSE on failure.

◆ M_hash_dict_serialize()

char * M_hash_dict_serialize	(	const M_hash_dict_t *	dict,
		char	delim,
		char	kv_delim,
		char	quote,
		char	escape,
		M_uint32	flags
	)

Serialize a dictionary into a string as per the definition.

Parameters

[in]	dict	Dictionary to serialize
[in]	delim	Delimiter between key/value pairs (recommended ';')
[in]	kv_delim	Delimiter between the key and value (recommended '=')
[in]	quote	Quote character (recommended '"')
[in]	escape	Escape character (recommended '\' or '"')
[in]	flags	Bitmap of possible M_hash_dict_ser_flag_t flags

Returns: String of serialized data, or NULL on failure.

◆ M_hash_dict_deserialize()

M_hash_dict_t * M_hash_dict_deserialize	(	const char *	str,
		size_t	len,
		char	delim,
		char	kv_delim,
		char	quote,
		char	escape,
		M_uint32	flags
	)

Deserialize a string into a hashtable as per the definition.

Parameters

[in]	str	String to deserialize
[in]	len	Length of string
[in]	delim	Delimiter between key/value pairs (recommended ';')
[in]	kv_delim	Delimiter between the key and value (recommended '=')
[in]	quote	Quote character (recommended '"')
[in]	escape	Escape character (recommended '\' or '"')
[in]	flags	Bitmap of possible M_hash_dict_flags_t flags

Returns: Dictionary of key/value pairs, or NULL on failure to parse.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ M_hash_dict_t

◆ M_hash_dict_enum_t

Enumeration Type Documentation

◆ M_hash_dict_flags_t

◆ M_hash_dict_ser_flag_t

Function Documentation

◆ M_hash_dict_create()

◆ M_hash_dict_destroy()

◆ M_hash_dict_insert()

◆ M_hash_dict_remove()

◆ M_hash_dict_get()

◆ M_hash_dict_get_direct()

◆ M_hash_dict_get_direct_default()

◆ M_hash_dict_is_multi()

◆ M_hash_dict_multi_len()

◆ M_hash_dict_multi_get()

◆ M_hash_dict_multi_get_direct()

◆ M_hash_dict_multi_remove()

◆ M_hash_dict_size()

◆ M_hash_dict_num_collisions()

◆ M_hash_dict_num_expansions()

◆ M_hash_dict_num_keys()

◆ M_hash_dict_enumerate()

◆ M_hash_dict_enumerate_next()

◆ M_hash_dict_enumerate_free()

◆ M_hash_dict_merge()

◆ M_hash_dict_duplicate()

◆ M_hash_dict_serialize_buf()

◆ M_hash_dict_serialize()

◆ M_hash_dict_deserialize()