Dictionary
[Database]

---

Detailed Description

Generic object-oriented dictionary support. It implements a container which pairs pointer-sized keys with pointer-sized values. Values are accessed via arbitrary user-defined keys.

Data Structures
struct	peak_dict_init_entry
	Structure containing a key and value pair to be used at the creation of the dictionary. More...
struct	peak_dict_key_ops_s
	Structure containing the callbacks for keys of a dictionary. More...
struct	peak_dict_value_ops_s
	Structure containing the callbacks for values of a dictionary. More...
Typedefs
typedef __peak_dict *	peak_dict
	Opaque dictionary pointer type.
typedef void *(*	peak_dict_retain_callback )(const void *value)
	Dictionary's key or value retain callback.
typedef void(*	peak_dict_release_callback )(const void *value)
	Dictionary's key or value release callback.
typedef int(*	peak_dict_equal_callback )(const void *val1, const void *val2)
	Dictionary's key equal callback.
typedef uint32_t(*	peak_dict_hash_callback )(const void *value)
	Dictionary's key callback.
typedef void(*	peak_dict_apply_func )(const void *key, const void *value, void *context)
	Apply function pointer type. See peak_dict_apply().
Functions
peak_dict	peak_dict_create (const peak_dict_key_ops_s *key_ops, const peak_dict_value_ops_s *value_ops, const peak_dict_init_entry *init_values, int num_values)
	Create a new dictionary.
int	peak_dict_get_count (peak_dict dict)
	Returns the number of values currently in the dictionary.
const void *	peak_dict_get_value (peak_dict dict, const void *key)
	Retrieves the value associated with the given key.
void	peak_dict_get_all (peak_dict dict, const void **keys, const void **values)
	Retrieves all key and value pairs.
void	peak_dict_apply (peak_dict dict, peak_dict_apply_func applier, void *context)
	Call a function once for each value in the dictionary.
void	peak_dict_add (peak_dict dict, const void *key, const void *value)
	"Add if absent" a key and value pair to the dictionary.
void	peak_dict_set (peak_dict dict, const void *key, const void *value)
	"Add if absent, replace is present" a key and value pair.
void	peak_dict_replace (peak_dict dict, const void *key, const void *value)
	"Replace if present" a key and value pair.
void	peak_dict_remove (peak_dict dict, const void *key)
	Remove a key and value pair from the dictionary.
void	peak_dict_clear (peak_dict dict)
	Remove all values from the dictionary.
Variables
const peak_dict_key_ops_s	peak_dict_null_key_ops
const peak_dict_key_ops_s	peak_dict_null_key_ops
const peak_dict_key_ops_s	peak_dict_string_key_ops
const peak_dict_key_ops_s	peak_dict_string_key_ops
const peak_dict_key_ops_s	peak_dict_string_copy_key_ops
const peak_dict_key_ops_s	peak_dict_string_copy_key_ops
const peak_dict_key_ops_s	peak_dict_stringcase_key_ops
const peak_dict_key_ops_s	peak_dict_stringcase_key_ops
const peak_dict_key_ops_s	peak_dict_stringcase_copy_key_ops
const peak_dict_key_ops_s	peak_dict_stringcase_copy_key_ops
const peak_dict_value_ops_s	peak_dict_null_value_ops
const peak_dict_value_ops_s	peak_dict_null_value_ops
const peak_dict_value_ops_s	peak_dict_string_value_ops
const peak_dict_value_ops_s	peak_dict_string_value_ops
const peak_dict_value_ops_s	peak_dict_string_copy_value_ops
const peak_dict_value_ops_s	peak_dict_string_copy_value_ops

---

Typedef Documentation

typedef int(* peak_dict_equal_callback)(const void *val1, const void *val2)

Dictionary's key equal callback. Should return 0 if the objects match or another value otherwise (eg. 1).

typedef uint32_t(* peak_dict_hash_callback)(const void *value)

Dictionary's key callback. Should return a good 32-bits hash value.

---

Function Documentation

void peak_dict_add (  peak_dict  dict, const void *  key, const void *  value )

"Add if absent" a key and value pair to the dictionary. Parameters: dict  The dictionary reference. key  The key to add. It's retained by the dictionary using the retain callback provided when the dictionary was created. value  The value to add, associated with the previous key. It's retained by the dictionary using the retain callback provided when the dictionary was created.

void peak_dict_apply (  peak_dict  dict, peak_dict_apply_func  applier, void *  context )

Call a function once for each value in the dictionary. Parameters: dict  The dictionary reference. applier  The callback function. context  A pointer-sized user-defined value, which is passed to the applier function. This parameter is not used by the library itself otherwise.

void peak_dict_clear (  peak_dict  dict  )

Remove all values from the dictionary. Parameters: dict  The dictionary reference.

peak_dict peak_dict_create (  const peak_dict_key_ops_s *  key_ops, const peak_dict_value_ops_s *  value_ops, const peak_dict_init_entry *  init_values, int  num_values )

Create a new dictionary. All peak's dictionary are created mutable, you can always add or remove elements. Immutable dictionary might be added in the future. Parameters: key_ops  A pointer to an user-defined operations structure peak_dict_key_ops_s on keys. A copy of the pointed structure is made, so you can reuse or deallocate the structure after this call. value_ops  A pointer to an user-defined operations structure peak_dict_value_ops_s on values. A copy of the pointed structure is made, so you can reuse or deallocate the structure after this call. init_values  A C array of peak_dict_init_entry to be immediately added in the dictionary or NULL if you want to create an empty dictionary. The array can be freed after the call. The key's retain callback, if any, is called for each item. Same thing for each value. num_values  Number of peak_dict_init_entry structures in the init_values C array. Use 0 if you want an empty dictionary. Returns: A pointer to a new allocated dictionary or NULL if the operation failed. Use peak_release() when you want to dispose it.

void peak_dict_get_all (  peak_dict  dict, const void **  keys, const void **  values )

Retrieves all key and value pairs. This method fills the two buffers with the keys and values from the dictionary. The keys and values C arrays are parallel to each other but the order or the pairs is not defined. Parameters: dict  The dictionary reference. keys  A buffer large enough to hold all pointer-sized keys or NULL. values  A buffer large enough to hold all pointer-sized values or NULL.

int peak_dict_get_count (  peak_dict  dict  )

Returns the number of values currently in the dictionary. Parameters: dict  The dictionary reference. Returns: Number of values currently in the dictionary.

const void* peak_dict_get_value (  peak_dict  dict, const void *  key )

Retrieves the value associated with the given key. This method will use the hash and equal key callbacks provided when the dictionary was created. Parameters: dict  The dictionary reference. key  The key for which to find a match in the dictionary. Returns: Number of values currently in the dictionary.

void peak_dict_remove (  peak_dict  dict, const void *  key )

Remove a key and value pair from the dictionary. Parameters: dict  The dictionary reference. key  The key of the value to remove in the dictionary. They are released by the dictionary using the release callbacks provided when the dictionary was created, if any.

void peak_dict_replace (  peak_dict  dict, const void *  key, const void *  value )

"Replace if present" a key and value pair. Parameters: dict  The dictionary reference. key  The key of the value to replace in the dictionary. value  The value to replace, associated with the previous key. The old one is released by the dictionary using the release callback and the new one is retained using the retain callback, both provided when the dictionary was created.

void peak_dict_set (  peak_dict  dict, const void *  key, const void *  value )

"Add if absent, replace is present" a key and value pair. Parameters: dict  The dictionary reference. key  The key to set. If the key isn't already in the dictionary, it's retained using the retain callback provided when the dictionary was created. value  The value to set, associated with the previous key. It's retained by the dictionary using the retain callback provided when the dictionary was created.

---

Variable Documentation

const peak_dict_key_ops_s peak_dict_null_key_ops

Predefined callbacks structure appropriate for use when keys of a dictionary are unknown objects and you want nothing to be performed as retain/release, and you can't provide better equality or hashing function than pointer-related ones.

const peak_dict_key_ops_s peak_dict_null_key_ops

Initial value: { NULL, NULL, __peak_dict_ptr_equal, __peak_dict_ptr_hash } Predefined callbacks structure appropriate for use when keys of a dictionary are unknown objects and you want nothing to be performed as retain/release, and you can't provide better equality or hashing function than pointer-related ones.

const peak_dict_value_ops_s peak_dict_null_value_ops

Predefined callbacks structure appropriate for use when values of a dictionary are unknown objects.

const peak_dict_value_ops_s peak_dict_null_value_ops

Initial value: { NULL, NULL } Predefined callbacks structure appropriate for use when values of a dictionary are unknown objects.

const peak_dict_key_ops_s peak_dict_string_copy_key_ops

Predefined callbacks structure appropriate for use when keys of a dictionary are strings to be copied by the dictionary.

const peak_dict_key_ops_s peak_dict_string_copy_key_ops

Initial value: { (peak_dict_retain_callback)peak_strdup, (peak_dict_release_callback)peak_deallocate, __peak_dict_string_equal, __peak_dict_string_hash } Predefined callbacks structure appropriate for use when keys of a dictionary are strings to be copied by the dictionary.

const peak_dict_value_ops_s peak_dict_string_copy_value_ops

Predefined callbacks structure appropriate for use when values of a dictionary are strings to be copied by the dictionary.

const peak_dict_value_ops_s peak_dict_string_copy_value_ops

Initial value: { (peak_dict_retain_callback)peak_strdup, (peak_dict_release_callback)peak_deallocate } Predefined callbacks structure appropriate for use when values of a dictionary are strings to be copied by the dictionary.

const peak_dict_key_ops_s peak_dict_string_key_ops

Predefined callbacks structure appropriate for use when keys of a dictionary are constant strings.

const peak_dict_key_ops_s peak_dict_string_key_ops

Initial value: { NULL, NULL, __peak_dict_string_equal, __peak_dict_string_hash } Predefined callbacks structure appropriate for use when keys of a dictionary are constant strings.

const peak_dict_value_ops_s peak_dict_string_value_ops

Predefined callbacks structure appropriate for use when values of a dictionary are constant strings.

const peak_dict_value_ops_s peak_dict_string_value_ops

Initial value: { NULL, NULL } Predefined callbacks structure appropriate for use when values of a dictionary are constant strings.

const peak_dict_key_ops_s peak_dict_stringcase_copy_key_ops

Predefined callbacks structure appropriate for use when keys of a dictionary are strings ignoring case to be copied by the dictionary.

const peak_dict_key_ops_s peak_dict_stringcase_copy_key_ops

Initial value: { (peak_dict_retain_callback)peak_strdup, (peak_dict_release_callback)peak_deallocate, __peak_dict_stringcase_equal, __peak_dict_stringcase_hash } Predefined callbacks structure appropriate for use when keys of a dictionary are strings ignoring case to be copied by the dictionary.

const peak_dict_key_ops_s peak_dict_stringcase_key_ops

Predefined callbacks structure appropriate for use when keys of a dictionary are constant strings ignoring case.

const peak_dict_key_ops_s peak_dict_stringcase_key_ops

Initial value: { NULL, NULL, __peak_dict_stringcase_equal, __peak_dict_stringcase_hash } Predefined callbacks structure appropriate for use when keys of a dictionary are constant strings ignoring case.

---