Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

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_equals,
     prop_dictionary_keysym_value, 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_value(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 *data);

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

     prop_dictionary_t
     prop_dictionary_internalize_from_file(const char *path);

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_value(prop_dictionary_keysym_t keysym)
            Returns a 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)
            This is an alias of prop_object_externalize() provided for
            backwards compatibility.

     prop_dictionary_internalize(const char *data)
            This is a wrapper around prop_object_internalize() provided for
            backwards compatbility.  In order to preserve previous behavior,
            prop_dictionary_internalize() will fail if the resulting object is
            not a dictionary.

     prop_dictionary_externalize_to_file(prop_dictionary_t dict, const char
            *path)
            This is an alias of prop_object_externalize_to_file() provided for
            backwards compatibility.

     prop_dictionary_internalize_from_file(const char *path)
            This is a wrapper around prop_object_internalize_from_file()
            provided for backwards compatibility.

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.

NetBSD 11.99                    April 20, 2025                    NetBSD 11.99