/src/glib/glib/gstrvbuilder.c
Line | Count | Source (jump to first uncovered line) |
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 * |
61 | | g_strv_builder_new (void) |
62 | 0 | { |
63 | 0 | return (GStrvBuilder *) g_ptr_array_new_with_free_func (g_free); |
64 | 0 | } |
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 |
78 | | g_strv_builder_unref (GStrvBuilder *builder) |
79 | 0 | { |
80 | 0 | g_ptr_array_unref (&builder->array); |
81 | 0 | } |
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 * |
95 | | g_strv_builder_ref (GStrvBuilder *builder) |
96 | 0 | { |
97 | 0 | return (GStrvBuilder *) g_ptr_array_ref (&builder->array); |
98 | 0 | } |
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 |
110 | | g_strv_builder_add (GStrvBuilder *builder, |
111 | | const char *value) |
112 | 0 | { |
113 | 0 | g_ptr_array_add (&builder->array, g_strdup (value)); |
114 | 0 | } |
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 |
129 | | g_strv_builder_end (GStrvBuilder *builder) |
130 | 0 | { |
131 | | /* Add NULL terminator */ |
132 | 0 | g_ptr_array_add (&builder->array, NULL); |
133 | 0 | return (GStrv) g_ptr_array_steal (&builder->array, NULL); |
134 | 0 | } |