Branch data Line data Source code
1 : : /*
2 : : * Copyright © 2020 Canonical Ltd.
3 : : * Copyright © 2021 Alexandros Theodotou
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or
8 : : * modify it under the terms of the GNU Lesser General Public
9 : : * License as published by the Free Software Foundation; either
10 : : * version 2.1 of the License, or (at your option) any later version.
11 : : *
12 : : * This library is distributed in the hope that it will be useful,
13 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 : : * Lesser General Public License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General Public
18 : : * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 : : */
20 : :
21 : : #include "config.h"
22 : :
23 : : #include "gstrvbuilder.h"
24 : :
25 : : #include "garray.h"
26 : : #include "gmem.h"
27 : : #include "gmessages.h"
28 : :
29 : : /**
30 : : * GStrvBuilder:
31 : : *
32 : : * `GStrvBuilder` is a helper object to build a %NULL-terminated string arrays.
33 : : *
34 : : * The following example shows how to build a two element array:
35 : : *
36 : : * ```c
37 : : * g_autoptr(GStrvBuilder) builder = g_strv_builder_new ();
38 : : * g_strv_builder_add (builder, "hello");
39 : : * g_strv_builder_add (builder, "world");
40 : : *
41 : : * g_auto(GStrv) array = g_strv_builder_end (builder);
42 : : *
43 : : * g_assert_true (g_strv_equal (array, (const char *[]) { "hello", "world", NULL }));
44 : : * ```
45 : : *
46 : : * Since: 2.68
47 : : */
48 : :
49 : : struct _GStrvBuilder
50 : : {
51 : : GPtrArray array;
52 : : };
53 : :
54 : : /**
55 : : * g_strv_builder_new:
56 : : *
57 : : * Creates a new #GStrvBuilder with a reference count of 1.
58 : : * Use g_strv_builder_unref() on the returned value when no longer needed.
59 : : *
60 : : * Returns: (transfer full): the new #GStrvBuilder
61 : : *
62 : : * Since: 2.68
63 : : */
64 : : GStrvBuilder *
65 : 506 : g_strv_builder_new (void)
66 : : {
67 : 506 : return (GStrvBuilder *) g_ptr_array_new_with_free_func (g_free);
68 : : }
69 : :
70 : : /**
71 : : * g_strv_builder_unref:
72 : : * @builder: (transfer full): a #GStrvBuilder allocated by g_strv_builder_new()
73 : : *
74 : : * Decreases the reference count on @builder.
75 : : *
76 : : * In the event that there are no more references, releases all memory
77 : : * associated with the #GStrvBuilder.
78 : : *
79 : : * Since: 2.68
80 : : **/
81 : : void
82 : 507 : g_strv_builder_unref (GStrvBuilder *builder)
83 : : {
84 : 507 : g_ptr_array_unref (&builder->array);
85 : 507 : }
86 : :
87 : : /**
88 : : * g_strv_builder_unref_to_strv:
89 : : * @builder: (transfer full): a #GStrvBuilder
90 : : *
91 : : * Decreases the reference count on the string vector builder, and returns
92 : : * its contents as a `NULL`-terminated string array.
93 : : *
94 : : * This function is especially useful for cases where it's not possible
95 : : * to use `g_autoptr()`.
96 : : *
97 : : * ```c
98 : : * GStrvBuilder *builder = g_strv_builder_new ();
99 : : * g_strv_builder_add (builder, "hello");
100 : : * g_strv_builder_add (builder, "world");
101 : : *
102 : : * GStrv array = g_strv_builder_unref_to_strv (builder);
103 : : *
104 : : * g_assert_true (g_strv_equal (array, (const char *[]) { "hello", "world", NULL }));
105 : : *
106 : : * g_strfreev (array);
107 : : * ```
108 : : *
109 : : * Returns: (transfer full) (array zero-terminated=1): the constructed string
110 : : * array
111 : : *
112 : : * Since: 2.82
113 : : */
114 : : GStrv
115 : 8 : g_strv_builder_unref_to_strv (GStrvBuilder *builder)
116 : : {
117 : 8 : GStrv res = g_strv_builder_end (builder);
118 : :
119 : 8 : g_strv_builder_unref (builder);
120 : :
121 : 8 : return res;
122 : : }
123 : :
124 : : /**
125 : : * g_strv_builder_ref:
126 : : * @builder: (transfer none): a #GStrvBuilder
127 : : *
128 : : * Atomically increments the reference count of @builder by one.
129 : : * This function is thread-safe and may be called from any thread.
130 : : *
131 : : * Returns: (transfer full): The passed in #GStrvBuilder
132 : : *
133 : : * Since: 2.68
134 : : */
135 : : GStrvBuilder *
136 : 1 : g_strv_builder_ref (GStrvBuilder *builder)
137 : : {
138 : 1 : return (GStrvBuilder *) g_ptr_array_ref (&builder->array);
139 : : }
140 : :
141 : : /**
142 : : * g_strv_builder_add:
143 : : * @builder: a #GStrvBuilder
144 : : * @value: a string.
145 : : *
146 : : * Add a string to the end of the array.
147 : : *
148 : : * Since 2.68
149 : : */
150 : : void
151 : 474 : g_strv_builder_add (GStrvBuilder *builder,
152 : : const char *value)
153 : : {
154 : 474 : g_ptr_array_add (&builder->array, g_strdup (value));
155 : 474 : }
156 : :
157 : : /**
158 : : * g_strv_builder_addv:
159 : : * @builder: a #GStrvBuilder
160 : : * @value: (array zero-terminated=1): the vector of strings to add
161 : : *
162 : : * Appends all the strings in the given vector to the builder.
163 : : *
164 : : * Since 2.70
165 : : */
166 : : void
167 : 1 : g_strv_builder_addv (GStrvBuilder *builder,
168 : : const char **value)
169 : : {
170 : 1 : gsize i = 0;
171 : 1 : g_return_if_fail (builder != NULL);
172 : 1 : g_return_if_fail (value != NULL);
173 : 4 : for (i = 0; value[i] != NULL; i++)
174 : 3 : g_strv_builder_add (builder, value[i]);
175 : : }
176 : :
177 : : /**
178 : : * g_strv_builder_add_many:
179 : : * @builder: a #GStrvBuilder
180 : : * @...: one or more strings followed by %NULL
181 : : *
182 : : * Appends all the given strings to the builder.
183 : : *
184 : : * Since 2.70
185 : : */
186 : : void
187 : 2 : g_strv_builder_add_many (GStrvBuilder *builder,
188 : : ...)
189 : : {
190 : : va_list var_args;
191 : : const gchar *str;
192 : 2 : g_return_if_fail (builder != NULL);
193 : 2 : va_start (var_args, builder);
194 : 7 : while ((str = va_arg (var_args, gchar *)) != NULL)
195 : 5 : g_strv_builder_add (builder, str);
196 : 2 : va_end (var_args);
197 : : }
198 : :
199 : : /**
200 : : * g_strv_builder_take:
201 : : * @builder: a #GStrvBuilder
202 : : * @value: (transfer full): a string.
203 : : * Ownership of the string is transferred to the #GStrvBuilder
204 : : *
205 : : * Add a string to the end of the array. After @value belongs to the
206 : : * #GStrvBuilder and may no longer be modified by the caller.
207 : : *
208 : : * Since 2.80
209 : : */
210 : : void
211 : 14 : g_strv_builder_take (GStrvBuilder *builder,
212 : : char *value)
213 : : {
214 : 14 : g_ptr_array_add (&builder->array, value);
215 : 14 : }
216 : :
217 : : /**
218 : : * g_strv_builder_end:
219 : : * @builder: a #GStrvBuilder
220 : : *
221 : : * Ends the builder process and returns the constructed NULL-terminated string
222 : : * array. The returned value should be freed with g_strfreev() when no longer
223 : : * needed.
224 : : *
225 : : * Returns: (transfer full): the constructed string array.
226 : : *
227 : : * Since 2.68
228 : : */
229 : : GStrv
230 : 505 : g_strv_builder_end (GStrvBuilder *builder)
231 : : {
232 : : /* Add NULL terminator */
233 : 505 : g_ptr_array_add (&builder->array, NULL);
234 : 505 : return (GStrv) g_ptr_array_steal (&builder->array, NULL);
235 : : }
|
