PROP_DICTIONARY(3) | Library Functions Manual | PROP_DICTIONARY(3)

# NAME

`prop_dictionary`, `prop_dictionary_create`, `prop_dictionary_create_with_capacity`, `prop_dictionary_copy`, `prop_dictionary_copy_mutable`, `prop_dictionary_count`, `prop_dictionary_ensure_capacity`, `prop_dictionary_iterator`, `prop_dictionary_all_keys`, `prop_dictionary_make_immutable`, `prop_dictionary_mutable`, `prop_dictionary_get`, `prop_dictionary_set`, `prop_dictionary_remove`, `prop_dictionary_get_keysym`, `prop_dictionary_set_keysym`, `prop_dictionary_remove_keysym`, `prop_dictionary_externalize`, `prop_dictionary_internalize`, `prop_dictionary_externalize_to_file`, `prop_dictionary_internalize_from_file`, `prop_dictionary_externalize_to_pref`, `prop_dictionary_internalize_from_pref`, `prop_dictionary_equals`, `prop_dictionary_keysym_cstring_nocopy`, `prop_dictionary_keysym_equals` —
dictionary property collection object

# LIBRARY

Property Container Object Library (libprop, -lprop)

# SYNOPSIS

`#include <prop/proplib.h>`

prop_dictionary_t
`prop_dictionary_create`(void);

prop_dictionary_t
`prop_dictionary_create_with_capacity`(unsigned int capacity);

prop_dictionary_t
`prop_dictionary_copy`(prop_dictionary_t dict);

prop_dictionary_t
`prop_dictionary_copy_mutable`(prop_dictionary_t dict);

unsigned int
`prop_dictionary_count`(prop_dictionary_t dict);

bool
`prop_dictionary_ensure_capacity`(prop_dictionary_t dict, unsigned int capacity);

prop_object_iterator_t
`prop_dictionary_iterator`(prop_dictionary_t dict);

prop_array_t
`prop_dictionary_all_keys`(prop_dictionary_t dict);

void
`prop_dictionary_make_immutable`(prop_dictionary_t dict);

bool
`prop_dictionary_mutable`(prop_dictionary_t dict);

prop_object_t
`prop_dictionary_get`(prop_dictionary_t dict, const char *key);

bool
`prop_dictionary_set`(prop_dictionary_t dict, const char *key, prop_object_t obj);

void
`prop_dictionary_remove`(prop_dictionary_t dict, const char *key);

prop_object_t
`prop_dictionary_get_keysym`(prop_dictionary_t dict, prop_dictionary_keysym_t keysym);

bool
`prop_dictionary_set_keysym`(prop_dictionary_t dict, prop_dictionary_keysym_t keysym, prop_object_t obj);

void
`prop_dictionary_remove_keysym`(prop_dictionary_t dict, prop_dictionary_keysym_t keysym);

bool
`prop_dictionary_equals`(prop_dictionary_t dict1, prop_dictionary_t dict2);

const char *
`prop_dictionary_keysym_cstring_nocopy`(prop_dictionary_keysym_t sym);

bool
`prop_dictionary_keysym_equals`(prop_dictionary_keysym_t keysym1, prop_dictionary_keysym_t keysym2);

char *
`prop_dictionary_externalize`(prop_dictionary_t dict);

prop_dictionary_t
`prop_dictionary_internalize`(const char *xml);

bool
`prop_dictionary_externalize_to_file`(prop_dictionary_t dict, const char *path);

prop_dictionary_t
`prop_dictionary_internalize_from_file`(const char *path);

bool
`prop_dictionary_externalize_to_pref`(prop_dictionary_t dict, struct plistref *pref);

bool
`prop_dictionary_internalize_from_pref`(const struct plistref *pref, prop_dictionary_t *dictp);

# DESCRIPTION

The `prop_dictionary`() family of functions operate on the dictionary property collection object type. A dictionary is an unordered set of objects stored as key-value pairs.

`prop_dictionary_create`(void)
  Create an empty dictionary. The dictionary initially has no capacity. Returns `NULL` on failure.
`prop_dictionary_create_with_capacity`(unsigned int capacity)
  Create a dictionary with the capacity to store capacity objects. Returns `NULL` on failure.
`prop_dictionary_copy`(prop_dictionary_t dict)
  Copy a dictionary. The new dictionary has an initial capacity equal to the number of objects stored in the dictionary being copied. The new dictionary contains references to the original dictionary's objects, not copies of those objects (i.e. a shallow copy is made). If the original dictionary is immutable, the resulting dictionary is also immutable.
`prop_dictionary_copy_mutable`(prop_dictionary_t dict)
  Like `prop_dictionary_copy`(), except the resulting dictionary is always mutable.
`prop_dictionary_count`(prop_dictionary_t dict)
  Returns the number of objects stored in the dictionary.
`prop_dictionary_ensure_capacity`(prop_dictionary_t dict, unsigned int capacity)
  Ensure that the dictionary has a total capacity of capacity, including objects already stored in the dictionary. Returns `true` if the capacity of the dictionary is greater or equal to capacity or if the expansion of the dictionary's capacity was successful and `false` otherwise. If the supplied object isn't a dictionary, `false` is returned.
`prop_dictionary_iterator`(prop_dictionary_t dict)
  Create an iterator for the dictionary. The dictionary is retained by the iterator. A dictionary iterator returns the key symbols used to look up objects stored in the dictionary; to get the object itself, a dictionary lookup using this key symbol must be performed. Storing to or removing from the dictionary invalidates any active iterators for the dictionary. Returns `NULL` on failure.
`prop_dictionary_all_keys`(prop_dictionary_t dict)
  Return an array of all of the dictionary key symbols (prop_dictionary_keysym_t) in the dictionary. This provides a way to iterate over the items in the dictionary while retaining the ability to mutate the dictionary; instead of iterating over the dictionary itself, iterate over the array of keys. The caller is responsible for releasing the array. Returns `NULL` on failure.
`prop_dictionary_make_immutable`(prop_dictionary_t dict)
  Make dict immutable.
`prop_dictionary_mutable`(prop_dictionary_t dict)
  Returns `true` if the dictionary is mutable.
`prop_dictionary_get`(prop_dictionary_t dict, const char *key)
  Return the object stored in the dictionary with the key key. If no object is stored with the specified key, `NULL` is returned.
`prop_dictionary_set`(prop_dictionary_t dict, const char *key, prop_object_t obj)
  Store a reference to the object obj with the key key. The object will be retained by the dictionary. If the key already exists in the dictionary, the object associated with that key will be released and replaced with the new object. Returns `true` if storing the object was successful and `false` otherwise.
`prop_dictionary_remove`(prop_dictionary_t dict, const char *key)
  Remove the reference to the object stored in the dictionary with the key key. The object will be released.
`prop_dictionary_get_keysym`(prop_dictionary_t dict, prop_dictionary_keysym_t sym)
  Like `prop_dictionary_get`(), but the lookup is performed using a key symbol returned by a dictionary iterator. The results are undefined if the iterator used to obtain the key symbol is not associated with dict.
`prop_dictionary_set_keysym`(prop_dictionary_t dict, prop_dictionary_keysym_t sym, prop_object_t obj)
  Like `prop_dictionary_set`(), but the lookup of the object to replace is performed using a key symbol returned by a dictionary iterator. The results are undefined if the iterator used to obtain the key symbol is not associated with dict.
`prop_dictionary_remove_keysym`(prop_dictionary_t dict, prop_dictionary_keysym_t sym)
  Like `prop_dictionary_remove`(), but the lookup of the object to remove is performed using a key symbol returned by a dictionary iterator. The results are undefined if the iterator used to obtain the key symbol is not associated with dict.
`prop_dictionary_equals`(prop_dictionary_t dict1, prop_dictionary_t dict2)
  Returns `true` if the two dictionaries are equivalent. Note: Objects contained in the dictionary are compared by value, not by reference.
`prop_dictionary_keysym_cstring_nocopy`(prop_dictionary_keysym_t keysym)
  Returns an immutable reference to the dictionary key symbol's string value.
`prop_dictionary_keysym_equals`(prop_dictionary_keysym_t keysym1, prop_dictionary_keysym_t keysym2)
  Returns `true` if the two dictionary key symbols are equivalent.
`prop_dictionary_externalize`(prop_dictionary_t dict)
  Externalizes a dictionary, returning a NUL-terminated buffer containing the XML representation of the dictionary. The caller is responsible for freeing the returned buffer. If converting to the external representation fails for any reason, `NULL` is returned.

  In user space, the buffer is allocated using malloc(3). In the kernel, the buffer is allocated using malloc(9) using the malloc type `M_TEMP`.

`prop_dictionary_internalize`(const char *xml)
  Parse the XML representation of a property list in the NUL-terminated buffer xml and return the corresponding dictionary. Returns `NULL` if parsing fails for any reason.
`prop_dictionary_externalize_to_file`(prop_dictionary_t dict, const char *path)
  Externalizes a dictionary and writes it to the file specified by path. The file is saved with the mode `0666` as modified by the process's file creation mask (see umask(2)) and is written atomically. Returns `false` if externalizing or writing the dictionary fails for any reason.
`prop_dictionary_internalize_from_file`(const char *path)
  Reads the XML property list contained in the file specified by path, internalizes it, and returns the corresponding dictionary. Returns `NULL` on failure.
`prop_dictionary_externalize_to_pref`(prop_dictionary_t dict, struct plistref *pref)
  Externalizes a dictionary and packs it into the plistref specified by pref. Returns `false` if externalizing the dictionary fails for any reason.
`prop_dictionary_internalize_from_pref`(const struct plistref *pref, prop_dictionary_t *dictp)
  Reads the plistref specified by pref, internalizes it, and returns the corresponding dictionary. Returns `false` if internalizing or writing the dictionary fails for any reason.

# SEE ALSO

prop_array(3), prop_bool(3), prop_data(3), prop_dictionary_util(3), prop_number(3), prop_object(3), prop_string(3), proplib(3)

# HISTORY

The proplib(3) property container object library first appeared in NetBSD 4.0.

December 5, 2009 | NetBSD 9.0