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.