Updated: 2025/Nov/16
Please read Privacy Policy. It's for your privacy.
PROP_ARRAY(3) Library Functions Manual PROP_ARRAY(3)
NAME
prop_array, prop_array_create, prop_array_create_with_capacity,
prop_array_copy, prop_array_copy_mutable, prop_array_capacity,
prop_array_count, prop_array_ensure_capacity, prop_array_iterator,
prop_array_make_immutable, prop_array_mutable, prop_array_get,
prop_array_set, prop_array_add, prop_array_remove,
prop_array_externalize, prop_array_internalize,
prop_array_externalize_to_file, prop_array_internalize_from_file,
prop_array_equals - array property collection object
LIBRARY
Property Container Object Library (libprop, -lprop)
SYNOPSIS
#include <prop/proplib.h>
prop_array_t
prop_array_create(void);
prop_array_t
prop_array_create_with_capacity(unsigned int capacity);
prop_array_t
prop_array_copy(prop_array_t array);
prop_array_t
prop_array_copy_mutable(prop_array_t array);
unsigned int
prop_array_capacity(prop_array_t array);
unsigned int
prop_array_count(prop_array_t array);
bool
prop_array_ensure_capacity(prop_array_t array, unsigned int capacity);
prop_object_iterator_t
prop_array_iterator(prop_array_t array);
void
prop_array_make_immutable(prop_array_t array);
bool
prop_array_mutable(prop_array_t array);
prop_object_t
prop_array_get(prop_array_t array, unsigned int index);
bool
prop_array_set(prop_array_t array, unsigned int index,
prop_object_t obj);
bool
prop_array_add(prop_array_t array, prop_object_t obj);
void
prop_array_remove(prop_array_t array, unsigned int index);
char *
prop_array_externalize(prop_array_t array);
prop_array_t
prop_array_internalize(const char *data);
bool
prop_array_externalize_to_file(prop_array_t array, const char *path);
prop_array_t
prop_array_internalize_from_file(const char *path);
bool
prop_array_equals(prop_array_t array1, prop_array_t array2);
DESCRIPTION
The prop_array family of functions operate on the array property
collection object type. An array is an ordered set; an iterated array
will return objects in the same order with which they were stored.
prop_array_create(void)
Create an empty array. The array initially has no capacity.
Returns NULL on failure.
prop_array_create_with_capacity(unsigned int capacity)
Create an array with the capacity to store capacity objects.
Returns NULL on failure.
prop_array_copy(prop_array_t array)
Copy an array. The new array has an initial capacity equal to the
number of objects stored in the array being copied. The new array
contains references to the original array's objects, not copies of
those objects (i.e. a shallow copy is made). If the original
array is immutable, the resulting array is also immutable.
Returns NULL on failure.
prop_array_copy_mutable(prop_array_t array)
Like prop_array_copy(), except the resulting array is always
mutable.
prop_array_capacity(prop_array_t array)
Returns the total capacity of the array, including objects already
stored in the array. If the supplied object isn't an array, zero
is returned.
prop_array_count(prop_array_t array)
Returns the number of objects stored in the array. If the
supplied object isn't an array, zero is returned.
prop_array_ensure_capacity(prop_array_t array, unsigned int capacity)
Ensure that the array has a total capacity of capacity, including
objects already stored in the array. Returns true if the capacity
of the array is greater or equal to capacity or if expansion of
the array's capacity was successful and false otherwise.
prop_array_iterator(prop_array_t array)
Create an iterator for the array. The array is retained by the
iterator. An array iterator returns the object references stored
in the array. Storing to or removing from the array invalidates
any active iterators for the array. Returns NULL on failure.
prop_array_make_immutable(prop_array_t array)
Make array immutable.
prop_array_mutable(prop_array_t array)
Returns true if the array is mutable.
prop_array_get(prop_array_t array, unsigned int index)
Return the object stored at the array index index. Returns NULL
on failure.
prop_array_set(prop_array_t array, unsigned int index, prop_object_t obj)
Store a reference to the object obj at the array index index.
This function is not allowed to create holes in the array; the
caller must either be setting the object just beyond the existing
count or replacing an already existing object reference. The
object will be retained by the array. If an existing object
reference is being replaced, that object will be released.
Returns true if storing the object was successful and false
otherwise.
prop_array_add(prop_array_t array, prop_object_t obj)
Add a reference to the object obj to the array, appending to the
end and growing the array's capacity if necessary. The object
will be retained by the array. Returns true if storing the object
was successful and false otherwise.
During expansion, array's capacity is augmented by the EXPAND_STEP
constant, as defined in libprop/prop_array.c file, e.g.
#define EXPAND_STEP 16
prop_array_remove(prop_array_t array, unsigned int index)
Remove the reference to the object stored at array index index.
The object will be released and the array compacted following the
removal.
prop_array_externalize(prop_array_t array)
This is an alias of prop_object_externalize() provided for
backwards compatibility.
prop_array_internalize(const char *data)
This is a wrapper around prop_object_internalize() provided for
backwards compatbility. In order to preserve previous behavior,
prop_array_internalize() will fail if the resulting object is not
an array.
prop_array_externalize_to_file(prop_array_t array, const char *path)
This is an alias of prop_object_externalize_to_file() provided for
backwards compatibility.
prop_array_internalize_from_file(const char *path)
This is a wrapper around prop_object_internalize_from_file()
provided for backwards compatibility.
prop_array_equals(prop_array_t array1, prop_array_t array2)
Returns true if the two arrays are equivalent. If at least one of
the supplied objects isn't an array, false is returned. Note:
Objects contained in the array are compared by value, not by
reference.
SEE ALSO
prop_array_util(3), prop_bool(3), prop_data(3), prop_dictionary(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