path: root/static/netbsd/man3/prop_array.3

.\"	$NetBSD: prop_array.3,v 1.16 2025/04/23 02:58:52 thorpej Exp $
.\"
.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jason R. Thorpe.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 20, 2025
.Dt PROP_ARRAY 3
.Os
.Sh NAME
.Nm prop_array ,
.Nm prop_array_create ,
.Nm prop_array_create_with_capacity ,
.Nm prop_array_copy ,
.Nm prop_array_copy_mutable ,
.Nm prop_array_capacity ,
.Nm prop_array_count ,
.Nm prop_array_ensure_capacity ,
.Nm prop_array_iterator ,
.Nm prop_array_make_immutable ,
.Nm prop_array_mutable ,
.Nm prop_array_get ,
.Nm prop_array_set ,
.Nm prop_array_add ,
.Nm prop_array_remove ,
.Nm prop_array_externalize ,
.Nm prop_array_internalize ,
.Nm prop_array_externalize_to_file ,
.Nm prop_array_internalize_from_file ,
.Nm prop_array_equals
.Nd array property collection object
.Sh LIBRARY
.Lb libprop
.Sh SYNOPSIS
.In prop/proplib.h
.\"
.Ft prop_array_t
.Fn prop_array_create "void"
.Ft prop_array_t
.Fn prop_array_create_with_capacity "unsigned int capacity"
.\"
.Ft prop_array_t
.Fn prop_array_copy "prop_array_t array"
.Ft prop_array_t
.Fn prop_array_copy_mutable "prop_array_t array"
.\"
.Ft unsigned int
.Fn prop_array_capacity "prop_array_t array"
.Ft unsigned int
.Fn prop_array_count "prop_array_t array"
.Ft bool
.Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
.\"
.Ft prop_object_iterator_t
.Fn prop_array_iterator "prop_array_t array"
.\"
.Ft void
.Fn prop_array_make_immutable "prop_array_t array"
.Ft bool
.Fn prop_array_mutable "prop_array_t array"
.\"
.Ft prop_object_t
.Fn prop_array_get "prop_array_t array" "unsigned int index"
.Ft bool
.Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj"
.Ft bool
.Fn prop_array_add "prop_array_t array" "prop_object_t obj"
.Ft void
.Fn prop_array_remove "prop_array_t array" "unsigned int index"
.\"
.Ft char *
.Fn prop_array_externalize "prop_array_t array"
.Ft prop_array_t
.Fn prop_array_internalize "const char *data"
.\"
.Ft bool
.Fn prop_array_externalize_to_file "prop_array_t array" "const char *path"
.Ft prop_array_t
.Fn prop_array_internalize_from_file "const char *path"
.\"
.Ft bool
.Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
.Sh DESCRIPTION
The
.Nm
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.
.Bl -tag -width "xxxxx"
.It Fn prop_array_create "void"
Create an empty array.
The array initially has no capacity.
Returns
.Dv NULL
on failure.
.It Fn prop_array_create_with_capacity "unsigned int capacity"
Create an array with the capacity to store
.Fa capacity
objects.
Returns
.Dv NULL
on failure.
.It Fn 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
.Pq i.e. a shallow copy is made .
If the original array is immutable, the resulting array is also immutable.
Returns
.Dv NULL
on failure.
.It Fn prop_array_copy_mutable "prop_array_t array"
Like
.Fn prop_array_copy ,
except the resulting array is always mutable.
.It Fn 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.
.It Fn 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.
.It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
Ensure that the array has a total capacity of
.Fa capacity ,
including objects already stored in the array.
Returns
.Dv true
if the capacity of the array is greater or equal to
.Fa capacity
or if expansion of the array's capacity was successful
and
.Dv false
otherwise.
.It Fn 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
.Dv NULL
on failure.
.It Fn prop_array_make_immutable "prop_array_t array"
Make
.Fa array
immutable.
.It Fn prop_array_mutable "prop_array_t array"
Returns
.Dv true
if the array is mutable.
.It Fn prop_array_get "prop_array_t array" "unsigned int index"
Return the object stored at the array index
.Fa index .
Returns
.Dv NULL
on failure.
.It Fn prop_array_set "prop_array_t array" "unsigned int index" \
       "prop_object_t obj"
Store a reference to the object
.Fa obj
at the array index
.Fa 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
.Dv true
if storing the object was successful and
.Dv false
otherwise.
.It Fn prop_array_add "prop_array_t array" "prop_object_t obj"
Add a reference to the object
.Fa 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
.Dv true
if storing the object was successful and
.Dv false
otherwise.
.Pp
During expansion, array's capacity is augmented by the
.Dv EXPAND_STEP
constant, as defined in
.Pa libprop/prop_array.c
file, e.g.
.Pp
.Dl #define	EXPAND_STEP		16
.It Fn prop_array_remove "prop_array_t array" "unsigned int index"
Remove the reference to the object stored at array index
.Fa index .
The object will be released and the array compacted following
the removal.
.It Fn prop_array_externalize "prop_array_t array"
This is an alias of
.Fn prop_object_externalize
provided for backwards compatibility.
.It Fn prop_array_internalize "const char *data"
This is a wrapper around
.Fn prop_object_internalize
provided for backwards compatbility.
In order to preserve previous behavior,
.Fn prop_array_internalize
will fail if the resulting object is not an array.
.It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path"
This is an alias of
.Fn prop_object_externalize_to_file
provided for backwards compatibility.
.It Fn prop_array_internalize_from_file "const char *path"
This is a wrapper around
.Fn prop_object_internalize_from_file
provided for backwards compatibility.
.It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
Returns
.Dv true
if the two arrays are equivalent.
If at least one of the supplied objects isn't an array,
.Dv false
is returned.
Note: Objects contained in the array are compared by value, not by reference.
.El
.Sh SEE ALSO
.Xr prop_array_util 3 ,
.Xr prop_bool 3 ,
.Xr prop_data 3 ,
.Xr prop_dictionary 3 ,
.Xr prop_number 3 ,
.Xr prop_object 3 ,
.Xr prop_string 3 ,
.Xr proplib 3
.Sh HISTORY
The
.Xr proplib 3
property container object library first appeared in
.Nx 4.0 .