This file provides a lookup structure for key-value pairs. More...

#include <sc_containers.h>

Include dependency graph for sc_keyvalue.h:

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

Typedefs
typedef struct sc_keyvalue	sc_keyvalue_t
	The key-value container is an opaque structure.

typedef int(*	sc_keyvalue_foreach_t) (const char key, const sc_keyvalue_entry_type_t type, void entry, const void *u)
	Function to call on every key value pair. More...

Enumerations
enum	sc_keyvalue_entry_type_t { SC_KEYVALUE_ENTRY_NONE = 0 , SC_KEYVALUE_ENTRY_INT , SC_KEYVALUE_ENTRY_DOUBLE , SC_KEYVALUE_ENTRY_STRING , SC_KEYVALUE_ENTRY_POINTER }
	The values can have different types. More...

Functions
sc_keyvalue_t *	sc_keyvalue_new ()
	Create a new key-value container. More...

sc_keyvalue_t *	sc_keyvalue_newf (int dummy,...)
	Create a container and set one or more key-value pairs. More...

sc_keyvalue_t *	sc_keyvalue_newv (va_list ap)
	Create a container and set one or more key-value pairs. More...

void	sc_keyvalue_destroy (sc_keyvalue_t *kv)
	Free a key-value container and all internal memory for key storage. More...

sc_keyvalue_entry_type_t	sc_keyvalue_exists (sc_keyvalue_t kv, const char key)
	Routine to check existence of an entry. More...

sc_keyvalue_entry_type_t	sc_keyvalue_unset (sc_keyvalue_t kv, const char key)
	Routine to remove an entry. More...

int	sc_keyvalue_get_int (sc_keyvalue_t kv, const char key, int dvalue)
	Routines to retrieve an integer value by its key. More...

double	sc_keyvalue_get_double (sc_keyvalue_t kv, const char key, double dvalue)
	Retrieve a double value by its key. More...

const char *	sc_keyvalue_get_string (sc_keyvalue_t kv, const char key, const char *dvalue)
	Retrieve a string value by its key. More...

void *	sc_keyvalue_get_pointer (sc_keyvalue_t kv, const char key, void *dvalue)
	Retrieve a pointer value by its key. More...

int	sc_keyvalue_get_int_check (sc_keyvalue_t kv, const char key, int *status)
	Query an integer key with error checking. More...

void	sc_keyvalue_set_int (sc_keyvalue_t kv, const char key, int newvalue)
	Routine to set an integer value for a given key. More...

void	sc_keyvalue_set_double (sc_keyvalue_t kv, const char key, double newvalue)
	Routine to set a double value for a given key. More...

void	sc_keyvalue_set_string (sc_keyvalue_t kv, const char key, const char *newvalue)
	Routine to set a string value for a given key. More...

void	sc_keyvalue_set_pointer (sc_keyvalue_t kv, const char key, void *newvalue)
	Routine to set a pointer value for a given key. More...

void	sc_keyvalue_foreach (sc_keyvalue_t kv, sc_keyvalue_foreach_t fn, void user_data)
	Iterate through all stored key-value pairs. More...

Detailed Description

This file provides a lookup structure for key-value pairs.

Typedef Documentation

◆ sc_keyvalue_foreach_t

typedef int(* sc_keyvalue_foreach_t) (const char *key, const sc_keyvalue_entry_type_t type, void *entry, const void *u)

Function to call on every key value pair.

Parameters

[in]	key	The key for this pair
[in]	type	The type of entry
[in]	entry	Pointer to the entry
[in]	u	Arbitrary user data.

Returns: Return true if the traversal should continue, false to stop.

Enumeration Type Documentation

◆ sc_keyvalue_entry_type_t

enum sc_keyvalue_entry_type_t

The values can have different types.

Enumerator
SC_KEYVALUE_ENTRY_NONE	Designate an invalid situation.
SC_KEYVALUE_ENTRY_INT	Used for values of type int.
SC_KEYVALUE_ENTRY_DOUBLE	Used for values of type double.
SC_KEYVALUE_ENTRY_STRING	Used for values of type const char *.
SC_KEYVALUE_ENTRY_POINTER	Used for values of anonymous pointer type.

Function Documentation

◆ sc_keyvalue_destroy()

void sc_keyvalue_destroy ( sc_keyvalue_t * kv )

Free a key-value container and all internal memory for key storage.

Parameters

[in,out] kv The key-value container is invalidated by this call.

Examples: options.c.

◆ sc_keyvalue_exists()

sc_keyvalue_entry_type_t sc_keyvalue_exists	(	sc_keyvalue_t *	kv,
		const char *	key
	)

Routine to check existence of an entry.

Parameters

[in]	kv	Valid key-value container.
[in]	key	Lookup key to query.

Returns: The entry's type if found and SC_KEYVALUE_ENTRY_NONE otherwise.

◆ sc_keyvalue_foreach()

void sc_keyvalue_foreach	(	sc_keyvalue_t *	kv,
		sc_keyvalue_foreach_t	fn,
		void *	user_data
	)

Iterate through all stored key-value pairs.

Parameters

[in]	kv	Valid key-value container.
[in]	fn	Function to call on each key-value pair.
[in,out]	user_data	This pointer is passed through to fn.

◆ sc_keyvalue_get_double()

double sc_keyvalue_get_double	(	sc_keyvalue_t *	kv,
		const char *	key,
		double	dvalue
	)

Retrieve a double value by its key.

This function asserts that the key, if existing, points to the correct type.

Parameters

[in]	kv	Valid key-value container.
[in]	key	Lookup key, may or may not exist.
[in]	dvalue	Default value returned if key is not found.

Returns: If key is not present then dvalue is returned, otherwise the value stored under key.

◆ sc_keyvalue_get_int()

int sc_keyvalue_get_int	(	sc_keyvalue_t *	kv,
		const char *	key,
		int	dvalue
	)

Routines to retrieve an integer value by its key.

This function asserts that the key, if existing, points to the correct type.

Parameters

[in]	kv	Valid key-value container.
[in]	key	Lookup key, may or may not exist.
[in]	dvalue	Default value returned if key is not found.

Returns: If key is not present then dvalue is returned, otherwise the value stored under key.

◆ sc_keyvalue_get_int_check()

int sc_keyvalue_get_int_check	(	sc_keyvalue_t *	kv,
		const char *	key,
		int *	status
	)

Query an integer key with error checking.

We check whether the key is not found or it is of the wrong type. A default value to be returned on error can be passed in as *status. If status is NULL, then the result on error is undefined.

Parameters

[in]	kv	Valid key-value table.
[in]	key	Non-NULL key string.
[in,out]	status	If not NULL, set to 0 if there is no error, 1 if the key is not found, 2 if a value is found but its type is not integer, and return the input value *status on error.

Returns: On error we return *status if status is not NULL, and else an undefined value backed by an assertion. Without error, return the result of the lookup.

◆ sc_keyvalue_get_pointer()

void* sc_keyvalue_get_pointer	(	sc_keyvalue_t *	kv,
		const char *	key,
		void *	dvalue
	)

Retrieve a pointer value by its key.

This function asserts that the key, if existing, points to the correct type.

Parameters

[in]	kv	Valid key-value container.
[in]	key	Lookup key, may or may not exist.
[in]	dvalue	Default value returned if key is not found.

Returns: If key is not present then dvalue is returned, otherwise the value stored under key.

◆ sc_keyvalue_get_string()

const char* sc_keyvalue_get_string	(	sc_keyvalue_t *	kv,
		const char *	key,
		const char *	dvalue
	)

Retrieve a string value by its key.

This function asserts that the key, if existing, points to the correct type.

Parameters

[in]	kv	Valid key-value container.
[in]	key	Lookup key, may or may not exist.
[in]	dvalue	Default value returned if key is not found.

Returns: If key is not present then dvalue is returned, otherwise the value stored under key.

◆ sc_keyvalue_new()

sc_keyvalue_t* sc_keyvalue_new ( )

Create a new key-value container.

Returns: The container is ready to use.

Examples: options.c.

◆ sc_keyvalue_newf()

sc_keyvalue_t* sc_keyvalue_newf	(	int	dummy,
			...
	)

Create a container and set one or more key-value pairs.

Arguments come in pairs of 2: a static string "type:key" and a value. The type is the letter i, g, s, p for int, double, const char *, and void *, respectively.

Parameters

[in] dummy Not touched, just to use the varargs feature.

Returns: A key-value container initialized with the given entries.

◆ sc_keyvalue_newv()

sc_keyvalue_t* sc_keyvalue_newv ( va_list ap )

Create a container and set one or more key-value pairs.

This function works analogously to sc_keyvalue_newf. Arguments come in pairs of 2: a static string "type:key" and a value. The type is the letter i, g, s, p for int, double, const char *, and void *, respectively.

Parameters

[in] ap Varargs pointer; see stdarg.h for the syntax.

Returns: A key-value container initialized with the given entries.

◆ sc_keyvalue_set_double()

void sc_keyvalue_set_double	(	sc_keyvalue_t *	kv,
		const char *	key,
		double	newvalue
	)

Routine to set a double value for a given key.

Parameters

[in]	kv	Valid key-value table.
[in]	key	Non-NULL key to insert or replace. If it already exists, it must be of type double.
[in]	newvalue	New value will be stored under key.

◆ sc_keyvalue_set_int()

void sc_keyvalue_set_int	(	sc_keyvalue_t *	kv,
		const char *	key,
		int	newvalue
	)

Routine to set an integer value for a given key.

Parameters

[in]	kv	Valid key-value table.
[in]	key	Non-NULL key to insert or replace. If it already exists, it must be of type integer.
[in]	newvalue	New value will be stored under key.

Examples: options.c.

◆ sc_keyvalue_set_pointer()

void sc_keyvalue_set_pointer	(	sc_keyvalue_t *	kv,
		const char *	key,
		void *	newvalue
	)

Routine to set a pointer value for a given key.

Parameters

[in]	kv	Valid key-value table.
[in]	key	Non-NULL key to insert or replace. If it already exists, it must be of type pointer.
[in]	newvalue	New value will be stored under key.

◆ sc_keyvalue_set_string()

void sc_keyvalue_set_string	(	sc_keyvalue_t *	kv,
		const char *	key,
		const char *	newvalue
	)

Routine to set a string value for a given key.

Parameters

[in]	kv	Valid key-value table.
[in]	key	Non-NULL key to insert or replace. If it already exists, it must be of type string.
[in]	newvalue	New value will be stored under key.

◆ sc_keyvalue_unset()

sc_keyvalue_entry_type_t sc_keyvalue_unset	(	sc_keyvalue_t *	kv,
		const char *	key
	)

Routine to remove an entry.

Parameters

[in]	kv	Valid key-value container.
[in]	key	Lookup key to remove if it exists.

Returns: The entry's type if found and removed, SC_KEYVALUE_ENTRY_NONE otherwise.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ sc_keyvalue_foreach_t

Enumeration Type Documentation

◆ sc_keyvalue_entry_type_t

Function Documentation

◆ sc_keyvalue_destroy()

◆ sc_keyvalue_exists()

◆ sc_keyvalue_foreach()

◆ sc_keyvalue_get_double()

◆ sc_keyvalue_get_int()

◆ sc_keyvalue_get_int_check()

◆ sc_keyvalue_get_pointer()

◆ sc_keyvalue_get_string()

◆ sc_keyvalue_new()

◆ sc_keyvalue_newf()

◆ sc_keyvalue_newv()

◆ sc_keyvalue_set_double()

◆ sc_keyvalue_set_int()

◆ sc_keyvalue_set_pointer()

◆ sc_keyvalue_set_string()

◆ sc_keyvalue_unset()