1 /*
2 * Copyright © 2020 Canonical Ltd.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18 #include "config.h"
19
20 #include "gstrvbuilder.h"
21
22 #include "garray.h"
23 #include "gmem.h"
24
25 /**
26 * SECTION:gstrvbuilder
27 * @title: GStrvBuilder
28 * @short_description: Helper to create NULL-terminated string arrays.
29 *
30 * #GStrvBuilder is a method of easily building dynamically sized
31 * NULL-terminated string arrays.
32 *
33 * The following example shows how to build a two element array:
34 *
35 * |[<!-- language="C" -->
36 * g_autoptr(GStrvBuilder) builder = g_strv_builder_new ();
37 * g_strv_builder_add (builder, "hello");
38 * g_strv_builder_add (builder, "world");
39 * g_auto(GStrv) array = g_strv_builder_end (builder);
40 * ]|
41 *
42 * Since: 2.68
43 */
44
45 struct _GStrvBuilder
46 {
47 GPtrArray array;
48 };
49
50 /**
51 * g_strv_builder_new:
52 *
53 * Creates a new #GStrvBuilder with a reference count of 1.
54 * Use g_strv_builder_unref() on the returned value when no longer needed.
55 *
56 * Returns: (transfer full): the new #GStrvBuilder
57 *
58 * Since: 2.68
59 */
60 GStrvBuilder *
g_strv_builder_new(void)61 g_strv_builder_new (void)
62 {
63 return (GStrvBuilder *) g_ptr_array_new_with_free_func (g_free);
64 }
65
66 /**
67 * g_strv_builder_unref:
68 * @builder: (transfer full): a #GStrvBuilder allocated by g_strv_builder_new()
69 *
70 * Decreases the reference count on @builder.
71 *
72 * In the event that there are no more references, releases all memory
73 * associated with the #GStrvBuilder.
74 *
75 * Since: 2.68
76 **/
77 void
g_strv_builder_unref(GStrvBuilder * builder)78 g_strv_builder_unref (GStrvBuilder *builder)
79 {
80 g_ptr_array_unref (&builder->array);
81 }
82
83 /**
84 * g_strv_builder_ref:
85 * @builder: (transfer none): a #GStrvBuilder
86 *
87 * Atomically increments the reference count of @builder by one.
88 * This function is thread-safe and may be called from any thread.
89 *
90 * Returns: (transfer full): The passed in #GStrvBuilder
91 *
92 * Since: 2.68
93 */
94 GStrvBuilder *
g_strv_builder_ref(GStrvBuilder * builder)95 g_strv_builder_ref (GStrvBuilder *builder)
96 {
97 return (GStrvBuilder *) g_ptr_array_ref (&builder->array);
98 }
99
100 /**
101 * g_strv_builder_add:
102 * @builder: a #GStrvBuilder
103 * @value: a string.
104 *
105 * Add a string to the end of the array.
106 *
107 * Since 2.68
108 */
109 void
g_strv_builder_add(GStrvBuilder * builder,const char * value)110 g_strv_builder_add (GStrvBuilder *builder,
111 const char *value)
112 {
113 g_ptr_array_add (&builder->array, g_strdup (value));
114 }
115
116 /**
117 * g_strv_builder_end:
118 * @builder: a #GStrvBuilder
119 *
120 * Ends the builder process and returns the constructed NULL-terminated string
121 * array. The returned value should be freed with g_strfreev() when no longer
122 * needed.
123 *
124 * Returns: (transfer full): the constructed string array.
125 *
126 * Since 2.68
127 */
128 GStrv
g_strv_builder_end(GStrvBuilder * builder)129 g_strv_builder_end (GStrvBuilder *builder)
130 {
131 /* Add NULL terminator */
132 g_ptr_array_add (&builder->array, NULL);
133 return (GStrv) g_ptr_array_steal (&builder->array, NULL);
134 }
135