1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this file (string_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_STRING_LIST_H
24 #define __LIBRETRO_SDK_STRING_LIST_H
26 #include <retro_common_api.h>
34 union string_list_elem_attr
41 struct string_list_elem
45 union string_list_elem_attr attr;
50 struct string_list_elem *elems;
56 * string_list_find_elem:
57 * @list : pointer to string list
58 * @elem : element to find inside the string list.
60 * Searches for an element (@elem) inside the string list.
62 * @return Number of elements found, otherwise 0.
64 int string_list_find_elem(const struct string_list *list, const char *elem);
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.
72 * Searches for an element (@elem) inside the string list. Will
73 * also search for the same element prefixed by @prefix.
75 * Returns: true (1) if element could be found, otherwise false (0).
77 bool string_list_find_elem_prefix(const struct string_list *list,
78 const char *prefix, const char *elem);
82 * @str : string to turn into a string list
83 * @delim : delimiter character to use for splitting the string.
85 * Creates a new string list based on string @str, delimited by @delim.
87 * Returns: new string list if successful, otherwise NULL.
89 struct string_list *string_split(const char *str, const char *delim);
91 bool string_split_noalloc(struct string_list *list,
92 const char *str, const char *delim);
96 * @str : string to turn into a string list
97 * @delim : delimiter character to use for separating the string.
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 "".
103 * @return New string list if successful, otherwise NULL.
105 struct string_list *string_separate(char *str, const char *delim);
107 bool string_separate_noalloc(struct string_list *list,
108 char *str, const char *delim);
110 bool string_list_deinitialize(struct string_list *list);
112 bool string_list_initialize(struct string_list *list);
117 * Creates a new string list. Has to be freed manually.
119 * @return New string list if successful, otherwise NULL.
121 struct string_list *string_list_new(void);
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.
129 * Appends a new element to the string list.
131 * Hidden non-leaf function cost:
132 * - Calls string_list_capacity()
135 * @return true if successful, otherwise false.
137 bool string_list_append(struct string_list *list, const char *elem,
138 union string_list_elem_attr attr);
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.
147 * Appends a new element to the string list.
149 * Hidden non-leaf function cost:
150 * - Calls string_list_capacity()
154 * @return true if successful, otherwise false.
156 bool string_list_append_n(struct string_list *list, const char *elem,
157 unsigned length, union string_list_elem_attr attr);
161 * @list : pointer to string list object
163 * Frees a string list.
165 void string_list_free(struct string_list *list);
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.
174 * A string list will be joined/concatenated as a
175 * string to @buffer, delimited by @delim.
177 * NOTE: @buffer must be NULL-terminated.
179 * Hidden non-leaf function cost:
180 * - Calls strlen_size()
181 * - Calls strlcat x times in a loop
183 void string_list_join_concat(char *buffer, size_t size,
184 const struct string_list *list, const char *sep);
188 * @list : pointer to string list
189 * @idx : index of element in string list
190 * @str : value for the element.
192 * Set value of element inside string list.
194 * Hidden non-leaf function cost:
198 void string_list_set(struct string_list *list, unsigned idx,
201 struct string_list *string_list_clone(const struct string_list *src);