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_externalize_to_pref,
prop_array_internalize_from_pref,
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 *xml);
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_externalize_to_pref(
prop_array_t
array,
struct plistref
*pref);
bool
prop_array_internalize_from_pref(
const
struct plistref *pref,
prop_array_t *arrayp);
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)
- Externalizes an array, returning a NUL-terminated buffer
containing the XML representation of the array. 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_array_internalize(const
char *xml)
- Parse the XML representation of a property list in the
NUL-terminated buffer xml and return the
corresponding array. Returns
NULL
if parsing fails
for any reason.
-
-
- prop_array_externalize_to_file(prop_array_t
array, const char *path)
- Externalizes an array 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 array fails for any reason.
-
-
- prop_array_internalize_from_file(const
char *path)
- Reads the XML property list contained in the file specified
by path, internalizes it, and returns the
corresponding array. Returns
NULL
on failure.
-
-
- prop_array_externalize_to_pref(prop_array_t
array, struct plistref *pref)
- Externalizes an array and packs it into the plistref
specified by pref. Returns
false
if externalizing the array fails for any
reason.
-
-
- prop_array_internalize_from_pref(const
struct plistref *pref, prop_array_t
*arrayp)
- Reads the plistref specified by pref,
internalizes it, and returns the corresponding array. Returns
false
if internalizing or writing the array fails
for any reason.
-
-
- 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_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.