1.\" $NetBSD: prop_array.3,v 1.16 2025/04/23 02:58:52 thorpej Exp $ 2.\" 3.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 20, 2025 31.Dt PROP_ARRAY 3 32.Os 33.Sh NAME 34.Nm prop_array , 35.Nm prop_array_create , 36.Nm prop_array_create_with_capacity , 37.Nm prop_array_copy , 38.Nm prop_array_copy_mutable , 39.Nm prop_array_capacity , 40.Nm prop_array_count , 41.Nm prop_array_ensure_capacity , 42.Nm prop_array_iterator , 43.Nm prop_array_make_immutable , 44.Nm prop_array_mutable , 45.Nm prop_array_get , 46.Nm prop_array_set , 47.Nm prop_array_add , 48.Nm prop_array_remove , 49.Nm prop_array_externalize , 50.Nm prop_array_internalize , 51.Nm prop_array_externalize_to_file , 52.Nm prop_array_internalize_from_file , 53.Nm prop_array_equals 54.Nd array property collection object 55.Sh LIBRARY 56.Lb libprop 57.Sh SYNOPSIS 58.In prop/proplib.h 59.\" 60.Ft prop_array_t 61.Fn prop_array_create "void" 62.Ft prop_array_t 63.Fn prop_array_create_with_capacity "unsigned int capacity" 64.\" 65.Ft prop_array_t 66.Fn prop_array_copy "prop_array_t array" 67.Ft prop_array_t 68.Fn prop_array_copy_mutable "prop_array_t array" 69.\" 70.Ft unsigned int 71.Fn prop_array_capacity "prop_array_t array" 72.Ft unsigned int 73.Fn prop_array_count "prop_array_t array" 74.Ft bool 75.Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" 76.\" 77.Ft prop_object_iterator_t 78.Fn prop_array_iterator "prop_array_t array" 79.\" 80.Ft void 81.Fn prop_array_make_immutable "prop_array_t array" 82.Ft bool 83.Fn prop_array_mutable "prop_array_t array" 84.\" 85.Ft prop_object_t 86.Fn prop_array_get "prop_array_t array" "unsigned int index" 87.Ft bool 88.Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj" 89.Ft bool 90.Fn prop_array_add "prop_array_t array" "prop_object_t obj" 91.Ft void 92.Fn prop_array_remove "prop_array_t array" "unsigned int index" 93.\" 94.Ft char * 95.Fn prop_array_externalize "prop_array_t array" 96.Ft prop_array_t 97.Fn prop_array_internalize "const char *data" 98.\" 99.Ft bool 100.Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" 101.Ft prop_array_t 102.Fn prop_array_internalize_from_file "const char *path" 103.\" 104.Ft bool 105.Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" 106.Sh DESCRIPTION 107The 108.Nm 109family of functions operate on the array property collection object type. 110An array is an ordered set; an iterated array will return objects in the 111same order with which they were stored. 112.Bl -tag -width "xxxxx" 113.It Fn prop_array_create "void" 114Create an empty array. 115The array initially has no capacity. 116Returns 117.Dv NULL 118on failure. 119.It Fn prop_array_create_with_capacity "unsigned int capacity" 120Create an array with the capacity to store 121.Fa capacity 122objects. 123Returns 124.Dv NULL 125on failure. 126.It Fn prop_array_copy "prop_array_t array" 127Copy an array. 128The new array has an initial capacity equal to the number of objects stored 129in the array being copied. 130The new array contains references to the original array's objects, not 131copies of those objects 132.Pq i.e. a shallow copy is made . 133If the original array is immutable, the resulting array is also immutable. 134Returns 135.Dv NULL 136on failure. 137.It Fn prop_array_copy_mutable "prop_array_t array" 138Like 139.Fn prop_array_copy , 140except the resulting array is always mutable. 141.It Fn prop_array_capacity "prop_array_t array" 142Returns the total capacity of the array, including objects already stored 143in the array. 144If the supplied object isn't an array, zero is returned. 145.It Fn prop_array_count "prop_array_t array" 146Returns the number of objects stored in the array. 147If the supplied object isn't an array, zero is returned. 148.It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" 149Ensure that the array has a total capacity of 150.Fa capacity , 151including objects already stored in the array. 152Returns 153.Dv true 154if the capacity of the array is greater or equal to 155.Fa capacity 156or if expansion of the array's capacity was successful 157and 158.Dv false 159otherwise. 160.It Fn prop_array_iterator "prop_array_t array" 161Create an iterator for the array. 162The array is retained by the iterator. 163An array iterator returns the object references stored in the array. 164Storing to or removing from the array invalidates any active iterators for 165the array. 166Returns 167.Dv NULL 168on failure. 169.It Fn prop_array_make_immutable "prop_array_t array" 170Make 171.Fa array 172immutable. 173.It Fn prop_array_mutable "prop_array_t array" 174Returns 175.Dv true 176if the array is mutable. 177.It Fn prop_array_get "prop_array_t array" "unsigned int index" 178Return the object stored at the array index 179.Fa index . 180Returns 181.Dv NULL 182on failure. 183.It Fn prop_array_set "prop_array_t array" "unsigned int index" \ 184 "prop_object_t obj" 185Store a reference to the object 186.Fa obj 187at the array index 188.Fa index . 189This function is not allowed to create holes in the array; 190the caller must either be setting the object just beyond the existing 191count or replacing an already existing object reference. 192The object will be retained by the array. 193If an existing object reference is being replaced, that object will be 194released. 195Returns 196.Dv true 197if storing the object was successful and 198.Dv false 199otherwise. 200.It Fn prop_array_add "prop_array_t array" "prop_object_t obj" 201Add a reference to the object 202.Fa obj 203to the array, appending to the end and growing the array's capacity if 204necessary. 205The object will be retained by the array. 206Returns 207.Dv true 208if storing the object was successful and 209.Dv false 210otherwise. 211.Pp 212During expansion, array's capacity is augmented by the 213.Dv EXPAND_STEP 214constant, as defined in 215.Pa libprop/prop_array.c 216file, e.g. 217.Pp 218.Dl #define EXPAND_STEP 16 219.It Fn prop_array_remove "prop_array_t array" "unsigned int index" 220Remove the reference to the object stored at array index 221.Fa index . 222The object will be released and the array compacted following 223the removal. 224.It Fn prop_array_externalize "prop_array_t array" 225This is an alias of 226.Fn prop_object_externalize 227provided for backwards compatibility. 228.It Fn prop_array_internalize "const char *data" 229This is a wrapper around 230.Fn prop_object_internalize 231provided for backwards compatbility. 232In order to preserve previous behavior, 233.Fn prop_array_internalize 234will fail if the resulting object is not an array. 235.It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" 236This is an alias of 237.Fn prop_object_externalize_to_file 238provided for backwards compatibility. 239.It Fn prop_array_internalize_from_file "const char *path" 240This is a wrapper around 241.Fn prop_object_internalize_from_file 242provided for backwards compatibility. 243.It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" 244Returns 245.Dv true 246if the two arrays are equivalent. 247If at least one of the supplied objects isn't an array, 248.Dv false 249is returned. 250Note: Objects contained in the array are compared by value, not by reference. 251.El 252.Sh SEE ALSO 253.Xr prop_array_util 3 , 254.Xr prop_bool 3 , 255.Xr prop_data 3 , 256.Xr prop_dictionary 3 , 257.Xr prop_number 3 , 258.Xr prop_object 3 , 259.Xr prop_string 3 , 260.Xr proplib 3 261.Sh HISTORY 262The 263.Xr proplib 3 264property container object library first appeared in 265.Nx 4.0 . 266