Resync #2

Author: inactive123

include/lists/nested_list.h

@@ -0,0 +1,242 @@
+/* Copyright  (C) 2010-2020 The RetroArch team
+ *
+ * ---------------------------------------------------------------------------------------
+ * The following license statement only applies to this file (nested_list.h).
+ * ---------------------------------------------------------------------------------------
+ *
+ * Permission is hereby granted, free of charge,
+ * to any person obtaining a copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef __LIBRETRO_SDK_NESTED_LIST_H__
+#define __LIBRETRO_SDK_NESTED_LIST_H__
+
+#include <retro_common_api.h>
+
+#include <boolean.h>
+#include <stdlib.h>
+#include <stddef.h>
+
+RETRO_BEGIN_DECLS
+
+/* Prevent direct access to nested_list_* members */
+typedef struct nested_list_item nested_list_item_t;
+typedef struct nested_list nested_list_t;
+
+/**************************************/
+/* Initialisation / De-Initialisation */
+/**************************************/
+
+/**
+ * nested_list_init:
+ *
+ * Creates a new empty nested list. Returned pointer
+ * must be freed using nested_list_free.
+ *
+ * Returns: Valid nested_list_t pointer if successful,
+ * otherwise NULL.
+ */
+nested_list_t *nested_list_init(void);
+
+/**
+ * nested_list_free:
+ *
+ * @list : pointer to nested_list_t object
+ *
+ * Frees specified nested list.
+ */
+void nested_list_free(nested_list_t *list);
+
+/***********/
+/* Setters */
+/***********/
+
+/**
+ * nested_list_add_item:
+ *
+ * @list    : pointer to nested_list_t object
+ * @address : a delimited list of item identifiers,
+ *            corresponding to item 'levels'
+ * @delim   : delimiter to use when splitting @address
+ *            into individual ids
+ * @value   : optional value (user data) associated with
+ *            new list item. This is added to the last
+ *            item specified by @address
+ *
+ * Appends a new item to the specified nested list.
+ * If @delim is NULL, item is added to the top level
+ * list (@list itself) with id equal to @address.
+ * Otherwise, @address is split by @delim and each
+ * id is added as new 'layer'. For example:
+ *
+ * > @address = "one:two:three", @delim = ":" will
+ *   produce:
+ *      top_level_list:one
+ *                     `- "one" list:two
+ *                                   `- "two" list:three
+ *   where @value is assigned to the "two" list:three
+ *   item.
+ *
+ * Returns: true if successful, otherwise false. Will
+ * always return false if item specified by @address
+ * already exists in the nested list.
+ */
+bool nested_list_add_item(nested_list_t *list,
+      const char *address, const char *delim, const void *value);
+
+/***********/
+/* Getters */
+/***********/
+
+/**
+ * nested_list_get_size:
+ *
+ * @list : pointer to nested_list_t object
+ *
+ * Fetches the current size (number of items) in
+ * the specified list.
+ *
+ * Returns: list size.
+ */
+size_t nested_list_get_size(nested_list_t *list);
+
+/**
+ * nested_list_get_item:
+ *
+ * @list    : pointer to nested_list_t object
+ * @address : a delimited list of item identifiers,
+ *            corresponding to item 'levels'
+ * @delim   : delimiter to use when splitting @address
+ *            into individual ids
+ *
+ * Searches for (and returns) the list item corresponding
+ * to @address. If @delim is NULL, the top level list
+ * (@list itself) is searched for an item with an id
+ * equal to @address. Otherwise, @address is split by
+ * @delim and each id is searched for in a subsequent
+ * list level.
+ *
+ * Returns: valid nested_list_item_t pointer if item
+ * is found, otherwise NULL.
+ */
+nested_list_item_t *nested_list_get_item(nested_list_t *list,
+      const char *address, const char *delim);
+
+/**
+ * nested_list_get_item_idx:
+ *
+ * @list : pointer to nested_list_t object
+ * @idx  : item index
+ *
+ * Fetches the item corresponding to index @idx in
+ * the top level list (@list itself) of the specified
+ * nested list.
+ *
+ * Returns: valid nested_list_item_t pointer if item
+ * exists, otherwise NULL.
+ */
+nested_list_item_t *nested_list_get_item_idx(nested_list_t *list,
+      size_t idx);
+
+/**
+ * nested_list_item_get_parent:
+ *
+ * @list_item : pointer to nested_list_item_t object
+ *
+ * Fetches the parent item of the specified nested
+ * list item. If returned value is NULL, specified
+ * nested list item belongs to a top level list.
+ *
+ * Returns: valid nested_list_item_t pointer if item
+ * has a parent, otherwise NULL.
+ */
+nested_list_item_t *nested_list_item_get_parent(nested_list_item_t *list_item);
+
+/**
+ * nested_list_item_get_parent_list:
+ *
+ * @list_item : pointer to nested_list_item_t object
+ *
+ * Fetches a pointer to the nested list of which the
+ * specified list item is a direct member.
+ *
+ * Returns: valid nested_list_t pointer if successful,
+ * otherwise NULL.
+ */
+nested_list_t *nested_list_item_get_parent_list(nested_list_item_t *list_item);
+
+/**
+ * nested_list_item_get_children:
+ *
+ * @list_item : pointer to nested_list_item_t object
+ *
+ * Fetches a pointer to the nested list of child items
+ * belonging to the specified list item.
+ *
+ * Returns: valid nested_list_t pointer if item has
+ * children, otherwise NULL.
+ */
+nested_list_t *nested_list_item_get_children(nested_list_item_t *list_item);
+
+/**
+ * nested_list_item_get_id:
+ *
+ * @list_item : pointer to nested_list_item_t object
+ *
+ * Fetches the id string of the specified list item,
+ * as set by nested_list_add_item().
+ *
+ * Returns: item id if successful, otherwise NULL.
+ */
+const char *nested_list_item_get_id(nested_list_item_t *list_item);
+
+/**
+ * nested_list_item_get_address:
+ *
+ * @list_item : pointer to nested_list_item_t object
+ * @delim     : delimiter to use when concatenating
+ *              individual item ids into a an @address
+ *              string
+ * @address   : a delimited list of item identifiers,
+ *              corresponding to item 'levels'
+ * @len       : length of supplied @address char array
+ 
+ * Fetches a compound @address string corresponding to
+ * the specified item's 'position' in the top level
+ * nested list of which it is a member. The resultant
+ * @address may be used to find the item when calling
+ * nested_list_get_item() on the top level nested list.
+ *
+ * Returns: true if successful, otherwise false.
+ */
+bool nested_list_item_get_address(nested_list_item_t *list_item,
+      const char *delim, char *address, size_t len);
+
+/**
+ * nested_list_item_get_value:
+ *
+ * @list_item : pointer to nested_list_item_t object
+ *
+ * Fetches the value (user data) associated with the
+ * specified list item.
+ *
+ * Returns: pointer to user data if set, otherwise
+ * NULL.
+ */
+const void *nested_list_item_get_value(nested_list_item_t *list_item);
+
+RETRO_END_DECLS
+
+#endif