glib/grefstring.h

   1 /* grefstring.h: Reference counted strings
   2  *
   3  * Copyright 2018  Emmanuele Bassi
   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 #pragma once
  22
  23 #include "gmem.h"
  24 #include "gmacros.h"
  25
  26 G_BEGIN_DECLS
  27
  28 GLIB_AVAILABLE_IN_2_58
  29 char *  g_ref_string_new        (const char *str);
  30 GLIB_AVAILABLE_IN_2_58
  31 char *  g_ref_string_new_len    (const char *str,
  32                                  gssize      len);
  33 GLIB_AVAILABLE_IN_2_58
  34 char *  g_ref_string_new_intern (const char *str);
  35
  36 GLIB_AVAILABLE_IN_2_58
  37 char *  g_ref_string_acquire    (char       *str);
  38 GLIB_AVAILABLE_IN_2_58
  39 void    g_ref_string_release    (char       *str);
  40
  41 GLIB_AVAILABLE_IN_2_58
  42 gsize   g_ref_string_length     (char       *str);
  43
  44 /**
  45  * GRefString:
  46  *
  47  * A typedef for a reference-counted string. A pointer to a #GRefString can be
  48  * treated like a standard `char*` array by all code, but can additionally have
  49  * `g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be
  50  * called on `char*` arrays not allocated using g_ref_string_new().
  51  *
  52  * If using #GRefString with autocleanups, g_autoptr() must be used rather than
  53  * g_autofree(), so that the reference counting metadata is also freed.
  54  *
  55  * Since: 2.58
  56  */
  57 typedef char GRefString;
  58
  59 G_END_DECLS