deps/libretro-common/include/lists/nested_list.h

   1 /* Copyright  (C) 2010-2020 The RetroArch team
   2  *
   3  * ---------------------------------------------------------------------------------------
   4  * The following license statement only applies to this file (nested_list.h).
   5  * ---------------------------------------------------------------------------------------
   6  *
   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:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  14  *
  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.
  21  */
  22
  23 #ifndef __LIBRETRO_SDK_NESTED_LIST_H__
  24 #define __LIBRETRO_SDK_NESTED_LIST_H__
  25
  26 #include <retro_common_api.h>
  27
  28 #include <boolean.h>
  29 #include <stdlib.h>
  30 #include <stddef.h>
  31
  32 RETRO_BEGIN_DECLS
  33
  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;
  37
  38 /**************************************/
  39 /* Initialisation / De-Initialisation */
  40 /**************************************/
  41
  42 /**
  43  * nested_list_init:
  44  *
  45  * Creates a new empty nested list. Returned pointer
  46  * must be freed using nested_list_free.
  47  *
  48  * Returns: Valid nested_list_t pointer if successful,
  49  * otherwise NULL.
  50  */
  51 nested_list_t *nested_list_init(void);
  52
  53 /**
  54  * nested_list_free:
  55  *
  56  * @list : pointer to nested_list_t object
  57  *
  58  * Frees specified nested list.
  59  */
  60 void nested_list_free(nested_list_t *list);
  61
  62 /***********/
  63 /* Setters */
  64 /***********/
  65
  66 /**
  67  * nested_list_add_item:
  68  *
  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
  73  *            into individual ids
  74  * @value   : optional value (user data) associated with
  75  *            new list item. This is added to the last
  76  *            item specified by @address
  77  *
  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:
  83  *
  84  * > @address = "one:two:three", @delim = ":" will
  85  *   produce:
  86  *      top_level_list:one
  87  *                     `- "one" list:two
  88  *                                   `- "two" list:three
  89  *   where @value is assigned to the "two" list:three
  90  *   item.
  91  *
  92  * Returns: true if successful, otherwise false. Will
  93  * always return false if item specified by @address
  94  * already exists in the nested list.
  95  */
  96 bool nested_list_add_item(nested_list_t *list,
  97       const char *address, const char *delim, const void *value);
  98
  99 /***********/
 100 /* Getters */
 101 /***********/
 102
 103 /**
 104  * nested_list_get_size:
 105  *
 106  * @list : pointer to nested_list_t object
 107  *
 108  * Fetches the current size (number of items) in
 109  * the specified list.
 110  *
 111  * Returns: list size.
 112  */
 113 size_t nested_list_get_size(nested_list_t *list);
 114
 115 /**
 116  * nested_list_get_item:
 117  *
 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
 123  *
 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
 129  * list level.
 130  *
 131  * Returns: valid nested_list_item_t pointer if item
 132  * is found, otherwise NULL.
 133  */
 134 nested_list_item_t *nested_list_get_item(nested_list_t *list,
 135       const char *address, const char *delim);
 136
 137 /**
 138  * nested_list_get_item_idx:
 139  *
 140  * @list : pointer to nested_list_t object
 141  * @idx  : item index
 142  *
 143  * Fetches the item corresponding to index @idx in
 144  * the top level list (@list itself) of the specified
 145  * nested list.
 146  *
 147  * Returns: valid nested_list_item_t pointer if item
 148  * exists, otherwise NULL.
 149  */
 150 nested_list_item_t *nested_list_get_item_idx(nested_list_t *list,
 151       size_t idx);
 152
 153 /**
 154  * nested_list_item_get_parent:
 155  *
 156  * @list_item : pointer to nested_list_item_t object
 157  *
 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.
 161  *
 162  * Returns: valid nested_list_item_t pointer if item
 163  * has a parent, otherwise NULL.
 164  */
 165 nested_list_item_t *nested_list_item_get_parent(nested_list_item_t *list_item);
 166
 167 /**
 168  * nested_list_item_get_parent_list:
 169  *
 170  * @list_item : pointer to nested_list_item_t object
 171  *
 172  * Fetches a pointer to the nested list of which the
 173  * specified list item is a direct member.
 174  *
 175  * Returns: valid nested_list_t pointer if successful,
 176  * otherwise NULL.
 177  */
 178 nested_list_t *nested_list_item_get_parent_list(nested_list_item_t *list_item);
 179
 180 /**
 181  * nested_list_item_get_children:
 182  *
 183  * @list_item : pointer to nested_list_item_t object
 184  *
 185  * Fetches a pointer to the nested list of child items
 186  * belonging to the specified list item.
 187  *
 188  * Returns: valid nested_list_t pointer if item has
 189  * children, otherwise NULL.
 190  */
 191 nested_list_t *nested_list_item_get_children(nested_list_item_t *list_item);
 192
 193 /**
 194  * nested_list_item_get_id:
 195  *
 196  * @list_item : pointer to nested_list_item_t object
 197  *
 198  * Fetches the id string of the specified list item,
 199  * as set by nested_list_add_item().
 200  *
 201  * Returns: item id if successful, otherwise NULL.
 202  */
 203 const char *nested_list_item_get_id(nested_list_item_t *list_item);
 204
 205 /**
 206  * nested_list_item_get_address:
 207  *
 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
 211  *              string
 212  * @address   : a delimited list of item identifiers,
 213  *              corresponding to item 'levels'
 214  * @len       : length of supplied @address char array
 215
 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.
 221  *
 222  * Returns: true if successful, otherwise false.
 223  */
 224 bool nested_list_item_get_address(nested_list_item_t *list_item,
 225       const char *delim, char *address, size_t len);
 226
 227 /**
 228  * nested_list_item_get_value:
 229  *
 230  * @list_item : pointer to nested_list_item_t object
 231  *
 232  * Fetches the value (user data) associated with the
 233  * specified list item.
 234  *
 235  * Returns: pointer to user data if set, otherwise
 236  * NULL.
 237  */
 238 const void *nested_list_item_get_value(nested_list_item_t *list_item);
 239
 240 RETRO_END_DECLS
 241
 242 #endif