matrixfurry.com
The open source OpenXR runtime
1// Copyright 2021, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief A collection of strings, like a list of extensions to enable
6 *
7 * @author Rylie Pavlik <rylie.pavlik@collabora.com>
8 * @ingroup aux_util
9 *
10 */
11#pragma once
12
13#include <stdint.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19
20/*!
21 * @brief A collection of string literals (const char *), such as used for extension name lists.
22 *
23 * @see xrt::auxiliary::util::StringList
24 */
25struct u_string_list;
26
27/*!
28 * @brief Create a string list with room for at least the given number of strings.
29 *
30 * @public @memberof u_string_list
31 */
32struct u_string_list *
33u_string_list_create(void);
34
35/*!
36 * @brief Create a string list with room for at least the given number of strings.
37 *
38 * @public @memberof u_string_list
39 */
40struct u_string_list *
41u_string_list_create_with_capacity(uint32_t capacity);
42
43/*!
44 * @brief Create a new string list from an existing string list.
45 *
46 * @public @memberof u_string_list
47 */
48struct u_string_list *
49u_string_list_create_from_list(struct u_string_list *usl);
50
51/*!
52 * @brief Create a new string list from an array of suitable strings.
53 *
54 * @param arr an array of zero or more non-null, null-terminated string that must live at least as long as the list,
55 * preferably string literals.
56 * @param size the number of elements in the array.
57 *
58 * @public @memberof u_string_list
59 */
60struct u_string_list *
61u_string_list_create_from_array(const char *const *arr, uint32_t size);
62
63/*!
64 * @brief Retrieve the number of elements in the list
65 *
66 * @public @memberof u_string_list
67 */
68uint32_t
69u_string_list_get_size(const struct u_string_list *usl);
70
71/*!
72 * @brief Retrieve the data pointer of the list
73 *
74 * @public @memberof u_string_list
75 */
76const char *const *
77u_string_list_get_data(const struct u_string_list *usl);
78
79/*!
80 * @brief Append a new string literal to the list.
81 *
82 * @param usl self pointer
83 * @param str a non-null, null-terminated string that must live at least as long as the list, preferably a string
84 * literal.
85 * @return 1 if successfully added, negative for errors.
86 *
87 * @public @memberof u_string_list
88 */
89int
90u_string_list_append(struct u_string_list *usl, const char *str);
91
92
93/*!
94 * @brief Append an array of new string literals to the list.
95 *
96 * @param usl self pointer
97 * @param arr an array of zero or more non-null, null-terminated string that must live at least as long as the list,
98 * preferably string literals.
99 * @param size the number of elements in the array.
100 * @return 1 if successfully added, negative for errors.
101 *
102 * @public @memberof u_string_list
103 */
104int
105u_string_list_append_array(struct u_string_list *usl, const char *const *arr, uint32_t size);
106
107/*!
108 * @brief Append a new string literal to the list, if it's not the same as a string already in the list.
109 *
110 * (Comparing string contents, not pointers)
111 *
112 * @param usl self pointer
113 * @param str a non-null, null-terminated string that must live at least as long as the list, preferably a string
114 * literal.
115 * @return 1 if successfully added, 0 if already existing so not added, negative for errors.
116 *
117 * @public @memberof u_string_list
118 */
119int
120u_string_list_append_unique(struct u_string_list *usl, const char *str);
121
122/*!
123 * @brief Check if the string is in the list.
124 *
125 * (Comparing string contents, not pointers)
126 *
127 * @param usl self pointer
128 * @param str a non-null, null-terminated string.
129 *
130 * @return true if the string is in the list.
131 */
132bool
133u_string_list_contains(struct u_string_list *usl, const char *str);
134
135/*!
136 * @brief Destroy a string list.
137 *
138 * Performs null checks and sets your pointer to zero.
139 *
140 * @public @memberof u_string_list
141 */
142void
143u_string_list_destroy(struct u_string_list **list_ptr);
144
145#ifdef __cplusplus
146} // extern "C"
147#endif