glib-2.0/glib/grefstring.h

0001 /* grefstring.h: Reference counted strings
0002  *
0003  * Copyright 2018  Emmanuele Bassi
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public
0018  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  */
0020
0021 #pragma once
0022
0023 #include "gmem.h"
0024 #include "gmacros.h"
0025
0026 G_BEGIN_DECLS
0027
0028 GLIB_AVAILABLE_IN_2_58
0029 char *  g_ref_string_new        (const char *str);
0030 GLIB_AVAILABLE_IN_2_58
0031 char *  g_ref_string_new_len    (const char *str,
0032                                  gssize      len);
0033 GLIB_AVAILABLE_IN_2_58
0034 char *  g_ref_string_new_intern (const char *str);
0035
0036 GLIB_AVAILABLE_IN_2_58
0037 char *  g_ref_string_acquire    (char       *str);
0038 GLIB_AVAILABLE_IN_2_58
0039 void    g_ref_string_release    (char       *str);
0040
0041 GLIB_AVAILABLE_IN_2_58
0042 gsize   g_ref_string_length     (char       *str);
0043
0044 /**
0045  * GRefString:
0046  *
0047  * A typedef for a reference-counted string. A pointer to a #GRefString can be
0048  * treated like a standard `char*` array by all code, but can additionally have
0049  * `g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be
0050  * called on `char*` arrays not allocated using g_ref_string_new().
0051  *
0052  * If using #GRefString with autocleanups, g_autoptr() must be used rather than
0053  * g_autofree(), so that the reference counting metadata is also freed.
0054  *
0055  * Since: 2.58
0056  */
0057 typedef char GRefString;
0058
0059 GLIB_AVAILABLE_IN_2_84
0060 gboolean g_ref_string_equal (const char *str1,
0061                              const char *str2);
0062
0063 G_END_DECLS