glib/gstrvbuilder.c

   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  * SECTION:gstrvbuilder
  31  * @title: GStrvBuilder
  32  * @short_description: Helper to create NULL-terminated string arrays.
  33  *
  34  * #GStrvBuilder is a method of easily building dynamically sized
  35  * NULL-terminated string arrays.
  36  *
  37  * The following example shows how to build a two element array:
  38  *
  39  * |[<!-- language="C" -->
  40  *   g_autoptr(GStrvBuilder) builder = g_strv_builder_new ();
  41  *   g_strv_builder_add (builder, "hello");
  42  *   g_strv_builder_add (builder, "world");
  43  *   g_auto(GStrv) array = g_strv_builder_end (builder);
  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 g_strv_builder_new (void)
  66 {
  67   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 g_strv_builder_unref (GStrvBuilder *builder)
  83 {
  84   g_ptr_array_unref (&builder->array);
  85 }
  86
  87 /**
  88  * g_strv_builder_ref:
  89  * @builder: (transfer none): a #GStrvBuilder
  90  *
  91  * Atomically increments the reference count of @builder by one.
  92  * This function is thread-safe and may be called from any thread.
  93  *
  94  * Returns: (transfer full): The passed in #GStrvBuilder
  95  *
  96  * Since: 2.68
  97  */
  98 GStrvBuilder *
  99 g_strv_builder_ref (GStrvBuilder *builder)
 100 {
 101   return (GStrvBuilder *) g_ptr_array_ref (&builder->array);
 102 }
 103
 104 /**
 105  * g_strv_builder_add:
 106  * @builder: a #GStrvBuilder
 107  * @value: a string.
 108  *
 109  * Add a string to the end of the array.
 110  *
 111  * Since 2.68
 112  */
 113 void
 114 g_strv_builder_add (GStrvBuilder *builder,
 115                     const char   *value)
 116 {
 117   g_ptr_array_add (&builder->array, g_strdup (value));
 118 }
 119
 120 /**
 121  * g_strv_builder_addv:
 122  * @builder: a #GStrvBuilder
 123  * @value: (array zero-terminated=1): the vector of strings to add
 124  *
 125  * Appends all the strings in the given vector to the builder.
 126  *
 127  * Since 2.70
 128  */
 129 void
 130 g_strv_builder_addv (GStrvBuilder *builder,
 131                      const char **value)
 132 {
 133   gsize i = 0;
 134   g_return_if_fail (builder != NULL);
 135   g_return_if_fail (value != NULL);
 136   for (i = 0; value[i] != NULL; i++)
 137     g_strv_builder_add (builder, value[i]);
 138 }
 139
 140 /**
 141  * g_strv_builder_add_many:
 142  * @builder: a #GStrvBuilder
 143  * @...: one or more strings followed by %NULL
 144  *
 145  * Appends all the given strings to the builder.
 146  *
 147  * Since 2.70
 148  */
 149 void
 150 g_strv_builder_add_many (GStrvBuilder *builder,
 151                          ...)
 152 {
 153   va_list var_args;
 154   const gchar *str;
 155   g_return_if_fail (builder != NULL);
 156   va_start (var_args, builder);
 157   while ((str = va_arg (var_args, gchar *)) != NULL)
 158     g_strv_builder_add (builder, str);
 159   va_end (var_args);
 160 }
 161
 162 /**
 163  * g_strv_builder_end:
 164  * @builder: a #GStrvBuilder
 165  *
 166  * Ends the builder process and returns the constructed NULL-terminated string
 167  * array. The returned value should be freed with g_strfreev() when no longer
 168  * needed.
 169  *
 170  * Returns: (transfer full): the constructed string array.
 171  *
 172  * Since 2.68
 173  */
 174 GStrv
 175 g_strv_builder_end (GStrvBuilder *builder)
 176 {
 177   /* Add NULL terminator */
 178   g_ptr_array_add (&builder->array, NULL);
 179   return (GStrv) g_ptr_array_steal (&builder->array, NULL);
 180 }