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 : 500 : g_strv_builder_new (void) 66 : : { 67 : 500 : 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 : 501 : g_strv_builder_unref (GStrvBuilder *builder) 83 : : { 84 : 501 : g_ptr_array_unref (&builder->array); 85 : 501 : } 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 : 2 : g_strv_builder_unref_to_strv (GStrvBuilder *builder) 116 : : { 117 : 2 : GStrv res = g_strv_builder_end (builder); 118 : : 119 : 2 : g_strv_builder_unref (builder); 120 : : 121 : 2 : 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 : 2 : g_strv_builder_take (GStrvBuilder *builder, 212 : : char *value) 213 : : { 214 : 2 : g_ptr_array_add (&builder->array, value); 215 : 2 : } 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 : 499 : g_strv_builder_end (GStrvBuilder *builder) 231 : : { 232 : : /* Add NULL terminator */ 233 : 499 : g_ptr_array_add (&builder->array, NULL); 234 : 499 : return (GStrv) g_ptr_array_steal (&builder->array, NULL); 235 : : }