1.\"	$NetBSD: prop_dictionary.3,v 1.22 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_DICTIONARY 3
32.Os
33.Sh NAME
34.Nm prop_dictionary ,
35.Nm prop_dictionary_create ,
36.Nm prop_dictionary_create_with_capacity ,
37.Nm prop_dictionary_copy ,
38.Nm prop_dictionary_copy_mutable ,
39.Nm prop_dictionary_count ,
40.Nm prop_dictionary_ensure_capacity ,
41.Nm prop_dictionary_iterator ,
42.Nm prop_dictionary_all_keys ,
43.Nm prop_dictionary_make_immutable ,
44.Nm prop_dictionary_mutable ,
45.Nm prop_dictionary_get ,
46.Nm prop_dictionary_set ,
47.Nm prop_dictionary_remove ,
48.Nm prop_dictionary_get_keysym ,
49.Nm prop_dictionary_set_keysym ,
50.Nm prop_dictionary_remove_keysym ,
51.Nm prop_dictionary_externalize ,
52.Nm prop_dictionary_internalize ,
53.Nm prop_dictionary_externalize_to_file ,
54.Nm prop_dictionary_internalize_from_file ,
55.Nm prop_dictionary_equals ,
56.Nm prop_dictionary_keysym_value ,
57.Nm prop_dictionary_keysym_equals
58.Nd dictionary property collection object
59.Sh LIBRARY
60.Lb libprop
61.Sh SYNOPSIS
62.In prop/proplib.h
63.\"
64.Ft prop_dictionary_t
65.Fn prop_dictionary_create "void"
66.Ft prop_dictionary_t
67.Fn prop_dictionary_create_with_capacity "unsigned int capacity"
68.\"
69.Ft prop_dictionary_t
70.Fn prop_dictionary_copy "prop_dictionary_t dict"
71.Ft prop_dictionary_t
72.Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
73.\"
74.Ft unsigned int
75.Fn prop_dictionary_count "prop_dictionary_t dict"
76.Ft bool
77.Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
78    "unsigned int capacity"
79.\"
80.Ft prop_object_iterator_t
81.Fn prop_dictionary_iterator "prop_dictionary_t dict"
82.Ft prop_array_t
83.Fn prop_dictionary_all_keys "prop_dictionary_t dict"
84.\"
85.Ft void
86.Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
87.Ft bool
88.Fn prop_dictionary_mutable "prop_dictionary_t dict"
89.\"
90.Ft prop_object_t
91.Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
92.Ft bool
93.Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
94    "prop_object_t obj"
95.Ft void
96.Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
97.\"
98.Ft prop_object_t
99.Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
100    "prop_dictionary_keysym_t keysym"
101.Ft bool
102.Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \
103    "prop_dictionary_keysym_t keysym" "prop_object_t obj"
104.Ft void
105.Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
106    "prop_dictionary_keysym_t keysym"
107.\"
108.Ft bool
109.Fn prop_dictionary_equals "prop_dictionary_t dict1" "prop_dictionary_t dict2"
110.\"
111.Ft const char *
112.Fn prop_dictionary_keysym_value "prop_dictionary_keysym_t sym"
113.\"
114.Ft bool
115.Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \
116    "prop_dictionary_keysym_t keysym2"
117.\"
118.Ft char *
119.Fn prop_dictionary_externalize "prop_dictionary_t dict"
120.Ft prop_dictionary_t
121.Fn prop_dictionary_internalize "const char *data"
122.\"
123.Ft bool
124.Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
125    "const char *path"
126.Ft prop_dictionary_t
127.Fn prop_dictionary_internalize_from_file "const char *path"
128.\"
129.Sh DESCRIPTION
130The
131.Nm
132family of functions operate on the dictionary property collection object type.
133A dictionary is an unordered set of objects stored as key-value pairs.
134.Bl -tag -width "xxxxx"
135.It Fn prop_dictionary_create "void"
136Create an empty dictionary.
137The dictionary initially has no capacity.
138Returns
139.Dv NULL
140on failure.
141.It Fn prop_dictionary_create_with_capacity "unsigned int capacity"
142Create a dictionary with the capacity to store
143.Fa capacity
144objects.
145Returns
146.Dv NULL
147on failure.
148.It Fn prop_dictionary_copy "prop_dictionary_t dict"
149Copy a dictionary.
150The new dictionary has an initial capacity equal to the number of objects
151stored in the dictionary being copied.
152The new dictionary contains references to the original dictionary's objects,
153not copies of those objects
154.Pq i.e. a shallow copy is made .
155If the original dictionary is immutable, the resulting dictionary is also
156immutable.
157.It Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
158Like
159.Fn prop_dictionary_copy ,
160except the resulting dictionary is always mutable.
161.It Fn prop_dictionary_count "prop_dictionary_t dict"
162Returns the number of objects stored in the dictionary.
163.It Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \
164    "unsigned int capacity"
165Ensure that the dictionary has a total capacity of
166.Fa capacity ,
167including objects already stored in the dictionary.
168Returns
169.Dv true
170if the capacity of the dictionary is greater or equal to
171.Fa capacity
172or if the expansion of the dictionary's capacity was successful
173and
174.Dv false
175otherwise.
176If the supplied object isn't a dictionary,
177.Dv false
178is returned.
179.It Fn prop_dictionary_iterator "prop_dictionary_t dict"
180Create an iterator for the dictionary.
181The dictionary is retained by the iterator.
182A dictionary iterator returns the key symbols used to look up objects stored
183in the dictionary; to get the object itself, a dictionary lookup using this
184key symbol must be performed.
185Storing to or removing from the dictionary invalidates any active iterators for
186the dictionary.
187Returns
188.Dv NULL
189on failure.
190.It Fn prop_dictionary_all_keys "prop_dictionary_t dict"
191Return an array of all of the dictionary key symbols
192.Pq prop_dictionary_keysym_t
193in the dictionary.
194This provides a way to iterate over the items in the dictionary while
195retaining the ability to mutate the dictionary; instead of iterating
196over the dictionary itself, iterate over the array of keys.
197The caller is responsible for releasing the array.
198Returns
199.Dv NULL
200on failure.
201.It Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
202Make
203.Fa dict
204immutable.
205.It Fn prop_dictionary_mutable "prop_dictionary_t dict"
206Returns
207.Dv true
208if the dictionary is mutable.
209.It Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key"
210Return the object stored in the dictionary with the key
211.Fa key .
212If no object is stored with the specified key,
213.Dv NULL
214is returned.
215.It Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \
216       "prop_object_t obj"
217Store a reference to the object
218.Fa obj
219with the key
220.Fa key .
221The object will be retained by the dictionary.
222If the key already exists in the dictionary, the object associated with
223that key will be released and replaced with the new object.
224Returns
225.Dv true
226if storing the object was successful and
227.Dv false
228otherwise.
229.It Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key"
230Remove the reference to the object stored in the dictionary with the key
231.Fa key .
232The object will be released.
233.It Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \
234    "prop_dictionary_keysym_t sym"
235Like
236.Fn prop_dictionary_get ,
237but the lookup is performed using a key symbol returned by a dictionary
238iterator.
239The results are undefined if the iterator used to obtain the key symbol
240is not associated with
241.Fa dict .
242.It Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \
243    "prop_dictionary_keysym_t sym" "prop_object_t obj"
244Like
245.Fn prop_dictionary_set ,
246but the lookup of the object to replace is performed using a key symbol
247returned by a dictionary iterator.
248The results are undefined if the iterator used to obtain the key symbol
249is not associated with
250.Fa dict .
251.It Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \
252    "prop_dictionary_keysym_t sym"
253Like
254.Fn prop_dictionary_remove ,
255but the lookup of the object to remove is performed using a key symbol
256returned by a dictionary iterator.
257The results are undefined if the iterator used to obtain the key symbol
258is not associated with
259.Fa dict .
260.It Fn prop_dictionary_equals "prop_dictionary_t dict1" \
261    "prop_dictionary_t dict2"
262Returns
263.Dv true
264if the two dictionaries are equivalent.
265Note: Objects contained in the dictionary are compared by value, not by
266reference.
267.It Fn prop_dictionary_keysym_value "prop_dictionary_keysym_t keysym"
268Returns a reference to the dictionary key symbol's string value.
269.It Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \
270    "prop_dictionary_keysym_t keysym2"
271Returns
272.Dv true
273if the two dictionary key symbols are equivalent.
274.It Fn prop_dictionary_externalize "prop_dictionary_t dict"
275This is an alias of
276.Fn prop_object_externalize
277provided for backwards compatibility.
278.It Fn prop_dictionary_internalize "const char *data"
279This is a wrapper around
280.Fn prop_object_internalize
281provided for backwards compatbility.
282In order to preserve previous behavior,
283.Fn prop_dictionary_internalize
284will fail if the resulting object is not a dictionary.
285.It Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \
286    "const char *path"
287This is an alias of
288.Fn prop_object_externalize_to_file
289provided for backwards compatibility.
290.It Fn prop_dictionary_internalize_from_file "const char *path"
291This is a wrapper around
292.Fn prop_object_internalize_from_file
293provided for backwards compatibility.
294.El
295.Sh SEE ALSO
296.Xr prop_array 3 ,
297.Xr prop_bool 3 ,
298.Xr prop_data 3 ,
299.Xr prop_dictionary_util 3 ,
300.Xr prop_number 3 ,
301.Xr prop_object 3 ,
302.Xr prop_string 3 ,
303.Xr proplib 3
304.Sh HISTORY
305The
306.Xr proplib 3
307property container object library first appeared in
308.Nx 4.0 .
309