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

   1 /* Copyright  (C) 2010-2020 The RetroArch team
   2  *
   3  * ---------------------------------------------------------------------------------------
   4  * The following license statement only applies to this file (string_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_STRING_LIST_H
  24 #define __LIBRETRO_SDK_STRING_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 union string_list_elem_attr
  35 {
  36    bool  b;
  37    int   i;
  38    void *p;
  39 };
  40
  41 struct string_list_elem
  42 {
  43    char *data;
  44    void *userdata;
  45    union string_list_elem_attr attr;
  46 };
  47
  48 struct string_list
  49 {
  50    struct string_list_elem *elems;
  51    size_t size;
  52    size_t cap;
  53 };
  54
  55 /**
  56  * string_list_find_elem:
  57  * @list             : pointer to string list
  58  * @elem             : element to find inside the string list.
  59  *
  60  * Searches for an element (@elem) inside the string list.
  61  *
  62  * @return Number of elements found, otherwise 0.
  63  */
  64 int string_list_find_elem(const struct string_list *list, const char *elem);
  65
  66 /**
  67  * string_list_find_elem_prefix:
  68  * @list             : pointer to string list
  69  * @prefix           : prefix to append to @elem
  70  * @elem             : element to find inside the string list.
  71  *
  72  * Searches for an element (@elem) inside the string list. Will
  73  * also search for the same element prefixed by @prefix.
  74  *
  75  * Returns: true (1) if element could be found, otherwise false (0).
  76  */
  77 bool string_list_find_elem_prefix(const struct string_list *list,
  78       const char *prefix, const char *elem);
  79
  80 /**
  81  * string_split:
  82  * @str              : string to turn into a string list
  83  * @delim            : delimiter character to use for splitting the string.
  84  *
  85  * Creates a new string list based on string @str, delimited by @delim.
  86  *
  87  * Returns: new string list if successful, otherwise NULL.
  88  */
  89 struct string_list *string_split(const char *str, const char *delim);
  90
  91 bool string_split_noalloc(struct string_list *list,
  92       const char *str, const char *delim);
  93
  94 /**
  95  * string_separate:
  96  * @str              : string to turn into a string list
  97  * @delim            : delimiter character to use for separating the string.
  98  *
  99  * Creates a new string list based on string @str, delimited by @delim.
 100  * Includes empty strings - i.e. two adjacent delimiters will resolve
 101  * to a string list element of "".
 102  *
 103  * @return New string list if successful, otherwise NULL.
 104  **/
 105 struct string_list *string_separate(char *str, const char *delim);
 106
 107 bool string_separate_noalloc(struct string_list *list,
 108       char *str, const char *delim);
 109
 110 bool string_list_deinitialize(struct string_list *list);
 111
 112 bool string_list_initialize(struct string_list *list);
 113
 114 /**
 115  * string_list_new:
 116  *
 117  * Creates a new string list. Has to be freed manually.
 118  *
 119  * @return New string list if successful, otherwise NULL.
 120  **/
 121 struct string_list *string_list_new(void);
 122
 123 /**
 124  * string_list_append:
 125  * @list             : pointer to string list
 126  * @elem             : element to add to the string list
 127  * @attr             : attributes of new element.
 128  *
 129  * Appends a new element to the string list.
 130
 131  * Hidden non-leaf function cost:
 132  * - Calls string_list_capacity()
 133  * - Calls strdup
 134  *
 135  * @return true if successful, otherwise false.
 136  **/
 137 bool string_list_append(struct string_list *list, const char *elem,
 138       union string_list_elem_attr attr);
 139
 140 /**
 141  * string_list_append_n:
 142  * @list             : pointer to string list
 143  * @elem             : element to add to the string list
 144  * @length           : read at most this many bytes from elem
 145  * @attr             : attributes of new element.
 146  *
 147  * Appends a new element to the string list.
 148  *
 149  * Hidden non-leaf function cost:
 150  * - Calls string_list_capacity()
 151  * - Calls malloc
 152  * - Calls strlcpy
 153  *
 154  * @return true if successful, otherwise false.
 155  **/
 156 bool string_list_append_n(struct string_list *list, const char *elem,
 157       unsigned length, union string_list_elem_attr attr);
 158
 159 /**
 160  * string_list_free
 161  * @list             : pointer to string list object
 162  *
 163  * Frees a string list.
 164  **/
 165 void string_list_free(struct string_list *list);
 166
 167 /**
 168  * string_list_join_concat:
 169  * @buffer           : buffer that @list will be joined to.
 170  * @size             : length of @buffer.
 171  * @list             : pointer to string list.
 172  * @delim            : delimiter character for @list.
 173  *
 174  * A string list will be joined/concatenated as a
 175  * string to @buffer, delimited by @delim.
 176  *
 177  * NOTE: @buffer must be NULL-terminated.
 178  *
 179  * Hidden non-leaf function cost:
 180  * - Calls strlen_size()
 181  * - Calls strlcat x times in a loop
 182  **/
 183 void string_list_join_concat(char *buffer, size_t size,
 184       const struct string_list *list, const char *sep);
 185
 186 /**
 187  * string_list_set:
 188  * @list             : pointer to string list
 189  * @idx              : index of element in string list
 190  * @str              : value for the element.
 191  *
 192  * Set value of element inside string list.
 193  *
 194  * Hidden non-leaf function cost:
 195  * - Calls free
 196  * - Calls strdup
 197  **/
 198 void string_list_set(struct string_list *list, unsigned idx,
 199       const char *str);
 200
 201 struct string_list *string_list_clone(const struct string_list *src);
 202
 203 RETRO_END_DECLS
 204
 205 #endif