\"      $NetBSD: prop_array.3,v 1.4 2006/08/21 04:13:28 thorpej Exp $
\"
\" Copyright (c) 2006 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.
\" 3. All advertising materials mentioning features or use of this software
\" must display the following acknowledgement:
\" This product includes software developed by the NetBSD
\" Foundation, Inc. and its contributors.
\" 4. Neither the name of The NetBSD Foundation nor the names of its
\" contributors may be used to endorse or promote products derived
\" from this software without specific prior written permission.
\"
\" 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 August 19, 2006
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 boolean_t
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 boolean_t
Fn prop_array_mutable "prop_array_t array"
\"
Ft prop_object_t
Fn prop_array_get "prop_array_t array" "unsigned int index"
Ft boolean_t
Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj"
Ft boolean_t
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 *xml"
\"
Ft boolean_t
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 boolean_t
Fn prop_array_equals "prop_array_t array1" "prop_array_t array2"
Sh DESCRIPTION
The
Nm 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.
Bl -tag -width "xxxxx"
It Fn prop_array_create "void"
Create an empty array.
The array initially has no capacity.
It Fn prop_array_create_with_capacity "unsigned int capacity"
Create an array with the capacity to store
Fa capacity
objects.
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.
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.
It Fn prop_array_count "prop_array_t array"
Returns the number of objects stored in the array.
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.
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 .
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 of
necessary.
The object will be retained by the array.
Returns
Dv TRUE
if storing the object was successful and
Dv FALSE
otherwise.
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_equals "prop_array_t array1" "prop_array_t array2"
Returns
Dv TRUE
if the two arrays are equivalent.
Note: Objects contained in the array are compared by value, not by reference.
It Fn 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,
Dv NULL
is returned.
Pp
In user space, the buffer is allocated using
Xr malloc 3 .
In the kernel, the buffer is allocated using
Xr malloc 9
using the malloc type
Dv M_TEMP .
It Fn prop_array_internalize "const char *xml"
Parse the XML representation of a property list in the NUL-terminated
buffer
Fa xml
and return the corresponding array.
Returns
Dv NULL
if parsing fails for any reason.
It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path"
Externalizes an array and writes it to the file specified by
Fa path .
The file is saved with the mode
Dv 0666
as modified by the process's file creation mask
Pq see Xr umask 3
and is written atomically.
Returns
Dv FALSE
if externalizing or writing the array fails for any reason.
It Fn prop_array_internalize_from_file "const char *path"
Reads the XML property list contained in the file specified by
Fa path ,
internalizes it, and returns the corresponding array.
El
Sh SEE ALSO
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
Nm proplib
property container object library first appeared in
Nx 4.0 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.