1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this file (nested_list.h).
5 * ---------------------------------------------------------------------------------------
7 * Permission is hereby granted, free of charge,
8 * to any person obtaining a copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
11 * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
16 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
19 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 #ifndef __LIBRETRO_SDK_NESTED_LIST_H__
24 #define __LIBRETRO_SDK_NESTED_LIST_H__
26 #include <retro_common_api.h>
34 /* Prevent direct access to nested_list_* members */
35 typedef struct nested_list_item nested_list_item_t;
36 typedef struct nested_list nested_list_t;
38 /**************************************/
39 /* Initialisation / De-Initialisation */
40 /**************************************/
45 * Creates a new empty nested list. Returned pointer
46 * must be freed using nested_list_free.
48 * Returns: Valid nested_list_t pointer if successful,
51 nested_list_t *nested_list_init(void);
56 * @list : pointer to nested_list_t object
58 * Frees specified nested list.
60 void nested_list_free(nested_list_t *list);
67 * nested_list_add_item:
69 * @list : pointer to nested_list_t object
70 * @address : a delimited list of item identifiers,
71 * corresponding to item 'levels'
72 * @delim : delimiter to use when splitting @address
74 * @value : optional value (user data) associated with
75 * new list item. This is added to the last
76 * item specified by @address
78 * Appends a new item to the specified nested list.
79 * If @delim is NULL, item is added to the top level
80 * list (@list itself) with id equal to @address.
81 * Otherwise, @address is split by @delim and each
82 * id is added as new 'layer'. For example:
84 * > @address = "one:two:three", @delim = ":" will
89 * where @value is assigned to the "two" list:three
92 * Returns: true if successful, otherwise false. Will
93 * always return false if item specified by @address
94 * already exists in the nested list.
96 bool nested_list_add_item(nested_list_t *list,
97 const char *address, const char *delim, const void *value);
104 * nested_list_get_size:
106 * @list : pointer to nested_list_t object
108 * Fetches the current size (number of items) in
109 * the specified list.
111 * Returns: list size.
113 size_t nested_list_get_size(nested_list_t *list);
116 * nested_list_get_item:
118 * @list : pointer to nested_list_t object
119 * @address : a delimited list of item identifiers,
120 * corresponding to item 'levels'
121 * @delim : delimiter to use when splitting @address
122 * into individual ids
124 * Searches for (and returns) the list item corresponding
125 * to @address. If @delim is NULL, the top level list
126 * (@list itself) is searched for an item with an id
127 * equal to @address. Otherwise, @address is split by
128 * @delim and each id is searched for in a subsequent
131 * Returns: valid nested_list_item_t pointer if item
132 * is found, otherwise NULL.
134 nested_list_item_t *nested_list_get_item(nested_list_t *list,
135 const char *address, const char *delim);
138 * nested_list_get_item_idx:
140 * @list : pointer to nested_list_t object
143 * Fetches the item corresponding to index @idx in
144 * the top level list (@list itself) of the specified
147 * Returns: valid nested_list_item_t pointer if item
148 * exists, otherwise NULL.
150 nested_list_item_t *nested_list_get_item_idx(nested_list_t *list,
154 * nested_list_item_get_parent:
156 * @list_item : pointer to nested_list_item_t object
158 * Fetches the parent item of the specified nested
159 * list item. If returned value is NULL, specified
160 * nested list item belongs to a top level list.
162 * Returns: valid nested_list_item_t pointer if item
163 * has a parent, otherwise NULL.
165 nested_list_item_t *nested_list_item_get_parent(nested_list_item_t *list_item);
168 * nested_list_item_get_parent_list:
170 * @list_item : pointer to nested_list_item_t object
172 * Fetches a pointer to the nested list of which the
173 * specified list item is a direct member.
175 * Returns: valid nested_list_t pointer if successful,
178 nested_list_t *nested_list_item_get_parent_list(nested_list_item_t *list_item);
181 * nested_list_item_get_children:
183 * @list_item : pointer to nested_list_item_t object
185 * Fetches a pointer to the nested list of child items
186 * belonging to the specified list item.
188 * Returns: valid nested_list_t pointer if item has
189 * children, otherwise NULL.
191 nested_list_t *nested_list_item_get_children(nested_list_item_t *list_item);
194 * nested_list_item_get_id:
196 * @list_item : pointer to nested_list_item_t object
198 * Fetches the id string of the specified list item,
199 * as set by nested_list_add_item().
201 * Returns: item id if successful, otherwise NULL.
203 const char *nested_list_item_get_id(nested_list_item_t *list_item);
206 * nested_list_item_get_address:
208 * @list_item : pointer to nested_list_item_t object
209 * @delim : delimiter to use when concatenating
210 * individual item ids into a an @address
212 * @address : a delimited list of item identifiers,
213 * corresponding to item 'levels'
214 * @len : length of supplied @address char array
216 * Fetches a compound @address string corresponding to
217 * the specified item's 'position' in the top level
218 * nested list of which it is a member. The resultant
219 * @address may be used to find the item when calling
220 * nested_list_get_item() on the top level nested list.
222 * Returns: true if successful, otherwise false.
224 bool nested_list_item_get_address(nested_list_item_t *list_item,
225 const char *delim, char *address, size_t len);
228 * nested_list_item_get_value:
230 * @list_item : pointer to nested_list_item_t object
232 * Fetches the value (user data) associated with the
233 * specified list item.
235 * Returns: pointer to user data if set, otherwise
238 const void *nested_list_item_get_value(nested_list_item_t *list_item);