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
45struct _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 */
60GStrvBuilder *
61g_strv_builder_new (void)
62{
63 return (GStrvBuilder *) g_ptr_array_new_with_free_func (element_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 **/
77void
78g_strv_builder_unref (GStrvBuilder *builder)
79{
80 g_ptr_array_unref (array: &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 */
94GStrvBuilder *
95g_strv_builder_ref (GStrvBuilder *builder)
96{
97 return (GStrvBuilder *) g_ptr_array_ref (array: &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 */
109void
110g_strv_builder_add (GStrvBuilder *builder,
111 const char *value)
112{
113 g_ptr_array_add (array: &builder->array, data: g_strdup (str: 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 */
128GStrv
129g_strv_builder_end (GStrvBuilder *builder)
130{
131 /* Add NULL terminator */
132 g_ptr_array_add (array: &builder->array, NULL);
133 return (GStrv) g_ptr_array_steal (array: &builder->array, NULL);
134}
135

source code of gtk/subprojects/glib/glib/gstrvbuilder.c