1/* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * SPDX-License-Identifier: LGPL-2.1-or-later
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 */
19
20/*
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
25 */
26
27#ifndef __G_STRING_H__
28#define __G_STRING_H__
29
30#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
31#error "Only <glib.h> can be included directly."
32#endif
33
34#include <glib/gtypes.h>
35#include <glib/gunicode.h>
36#include <glib/gbytes.h>
37#include <glib/gstrfuncs.h>
38#include <glib/gutils.h> /* for G_CAN_INLINE */
39#include <string.h>
40
41G_BEGIN_DECLS
42
43typedef struct _GString GString;
44
45struct _GString
46{
47 gchar *str;
48 gsize len;
49 gsize allocated_len;
50};
51
52GLIB_AVAILABLE_IN_ALL
53GString* g_string_new (const gchar *init);
54GLIB_AVAILABLE_IN_2_78
55GString* g_string_new_take (gchar *init);
56GLIB_AVAILABLE_IN_ALL
57GString* g_string_new_len (const gchar *init,
58 gssize len);
59GLIB_AVAILABLE_IN_ALL
60GString* g_string_sized_new (gsize dfl_size);
61GLIB_AVAILABLE_IN_ALL
62gchar* (g_string_free) (GString *string,
63 gboolean free_segment);
64GLIB_AVAILABLE_IN_2_76
65gchar* g_string_free_and_steal (GString *string) G_GNUC_WARN_UNUSED_RESULT;
66
67#if G_GNUC_CHECK_VERSION (2, 0) && (GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_76)
68
69#if !defined(__cplusplus) || !G_GNUC_CHECK_VERSION (6, 1) || G_GNUC_CHECK_VERSION (7, 3)
70
71#define g_string_free(str, free_segment) \
72 (__builtin_constant_p (free_segment) ? \
73 ((free_segment) ? \
74 (g_string_free) ((str), (free_segment)) : \
75 g_string_free_and_steal (str)) \
76 : \
77 (g_string_free) ((str), (free_segment)))
78
79#endif /* !defined(__cplusplus) || !G_GNUC_CHECK_VERSION (6, 1) || G_GNUC_CHECK_VERSION (7, 3) */
80
81#endif /* G_GNUC_CHECK_VERSION (2, 0) && (GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_76) */
82
83GLIB_AVAILABLE_IN_2_34
84GBytes* g_string_free_to_bytes (GString *string);
85GLIB_AVAILABLE_IN_ALL
86gboolean g_string_equal (const GString *v,
87 const GString *v2);
88GLIB_AVAILABLE_IN_ALL
89guint g_string_hash (const GString *str);
90GLIB_AVAILABLE_IN_ALL
91GString* g_string_assign (GString *string,
92 const gchar *rval);
93GLIB_AVAILABLE_IN_ALL
94GString* g_string_truncate (GString *string,
95 gsize len);
96GLIB_AVAILABLE_IN_ALL
97GString* g_string_set_size (GString *string,
98 gsize len);
99GLIB_AVAILABLE_IN_ALL
100GString* g_string_insert_len (GString *string,
101 gssize pos,
102 const gchar *val,
103 gssize len);
104GLIB_AVAILABLE_IN_ALL
105GString* g_string_append (GString *string,
106 const gchar *val);
107GLIB_AVAILABLE_IN_ALL
108GString* g_string_append_len (GString *string,
109 const gchar *val,
110 gssize len);
111GLIB_AVAILABLE_IN_ALL
112GString* g_string_append_c (GString *string,
113 gchar c);
114GLIB_AVAILABLE_IN_ALL
115GString* g_string_append_unichar (GString *string,
116 gunichar wc);
117GLIB_AVAILABLE_IN_ALL
118GString* g_string_prepend (GString *string,
119 const gchar *val);
120GLIB_AVAILABLE_IN_ALL
121GString* g_string_prepend_c (GString *string,
122 gchar c);
123GLIB_AVAILABLE_IN_ALL
124GString* g_string_prepend_unichar (GString *string,
125 gunichar wc);
126GLIB_AVAILABLE_IN_ALL
127GString* g_string_prepend_len (GString *string,
128 const gchar *val,
129 gssize len);
130GLIB_AVAILABLE_IN_ALL
131GString* g_string_insert (GString *string,
132 gssize pos,
133 const gchar *val);
134GLIB_AVAILABLE_IN_ALL
135GString* g_string_insert_c (GString *string,
136 gssize pos,
137 gchar c);
138GLIB_AVAILABLE_IN_ALL
139GString* g_string_insert_unichar (GString *string,
140 gssize pos,
141 gunichar wc);
142GLIB_AVAILABLE_IN_ALL
143GString* g_string_overwrite (GString *string,
144 gsize pos,
145 const gchar *val);
146GLIB_AVAILABLE_IN_ALL
147GString* g_string_overwrite_len (GString *string,
148 gsize pos,
149 const gchar *val,
150 gssize len);
151GLIB_AVAILABLE_IN_ALL
152GString* g_string_erase (GString *string,
153 gssize pos,
154 gssize len);
155GLIB_AVAILABLE_IN_2_68
156guint g_string_replace (GString *string,
157 const gchar *find,
158 const gchar *replace,
159 guint limit);
160GLIB_AVAILABLE_IN_ALL
161GString* g_string_ascii_down (GString *string);
162GLIB_AVAILABLE_IN_ALL
163GString* g_string_ascii_up (GString *string);
164GLIB_AVAILABLE_IN_ALL
165void g_string_vprintf (GString *string,
166 const gchar *format,
167 va_list args)
168 G_GNUC_PRINTF(2, 0);
169GLIB_AVAILABLE_IN_ALL
170void g_string_printf (GString *string,
171 const gchar *format,
172 ...) G_GNUC_PRINTF (2, 3);
173GLIB_AVAILABLE_IN_ALL
174void g_string_append_vprintf (GString *string,
175 const gchar *format,
176 va_list args)
177 G_GNUC_PRINTF(2, 0);
178GLIB_AVAILABLE_IN_ALL
179void g_string_append_printf (GString *string,
180 const gchar *format,
181 ...) G_GNUC_PRINTF (2, 3);
182GLIB_AVAILABLE_IN_ALL
183GString* g_string_append_uri_escaped (GString *string,
184 const gchar *unescaped,
185 const gchar *reserved_chars_allowed,
186 gboolean allow_utf8);
187
188#ifdef G_CAN_INLINE
189
190#if defined (_MSC_VER) && !defined (__clang__)
191#pragma warning (push)
192#pragma warning (disable : 4141) /* silence "warning C4141: 'inline' used more than once" */
193#endif
194
195#ifndef __GTK_DOC_IGNORE__
196
197G_ALWAYS_INLINE
198static inline GString*
199g_string_append_c_inline (GString *gstring,
200 gchar c)
201{
202 if (G_LIKELY (gstring != NULL &&
203 gstring->len + 1 < gstring->allocated_len))
204 {
205 gstring->str[gstring->len++] = c;
206 gstring->str[gstring->len] = 0;
207 }
208 else
209 g_string_insert_c (string: gstring, pos: -1, c);
210 return gstring;
211}
212
213#define g_string_append_c(gstr,c) \
214 g_string_append_c_inline (gstr, c)
215
216G_ALWAYS_INLINE
217static inline GString *
218g_string_append_len_inline (GString *gstring,
219 const char *val,
220 gssize len)
221{
222 gsize len_unsigned;
223
224 if G_UNLIKELY (gstring == NULL)
225 return g_string_append_len (string: gstring, val, len);
226
227 if G_UNLIKELY (val == NULL)
228 return (len != 0) ? g_string_append_len (string: gstring, val, len) : gstring;
229
230 if (len < 0)
231 len_unsigned = strlen (s: val);
232 else
233 len_unsigned = (gsize) len;
234
235 if (G_LIKELY (gstring->len + len_unsigned < gstring->allocated_len))
236 {
237 char *end = gstring->str + gstring->len;
238 if (G_LIKELY (val + len_unsigned <= end || val > end + len_unsigned))
239 memcpy (dest: end, src: val, n: len_unsigned);
240 else
241 memmove (dest: end, src: val, n: len_unsigned);
242 gstring->len += len_unsigned;
243 gstring->str[gstring->len] = 0;
244 return gstring;
245 }
246 else
247 return g_string_insert_len (string: gstring, pos: -1, val, len);
248}
249
250#define g_string_append_len(gstr, val, len) \
251 g_string_append_len_inline (gstr, val, len)
252
253G_ALWAYS_INLINE
254static inline GString *
255g_string_truncate_inline (GString *gstring,
256 gsize len)
257{
258 gstring->len = MIN (len, gstring->len);
259 gstring->str[gstring->len] = '\0';
260 return gstring;
261}
262
263#define g_string_truncate(gstr, len) \
264 g_string_truncate_inline (gstr, len)
265
266#if G_GNUC_CHECK_VERSION (2, 0)
267
268#define g_string_append(gstr, val) \
269 (__builtin_constant_p (val) ? \
270 G_GNUC_EXTENSION ({ \
271 const char * const __val = (val); \
272 g_string_append_len (gstr, __val, \
273 G_LIKELY (__val != NULL) ? \
274 (gssize) strlen (_G_STR_NONNULL (__val)) \
275 : (gssize) -1); \
276 }) \
277 : \
278 g_string_append_len (gstr, val, (gssize) -1))
279
280#endif /* G_GNUC_CHECK_VERSION (2, 0) */
281
282#endif /* __GTK_DOC_IGNORE__ */
283
284#if defined (_MSC_VER) && !defined (__clang__)
285#pragma warning (pop) /* #pragma warning (disable : 4141) */
286#endif
287
288#endif /* G_CAN_INLINE */
289
290GLIB_DEPRECATED
291GString *g_string_down (GString *string);
292GLIB_DEPRECATED
293GString *g_string_up (GString *string);
294
295#define g_string_sprintf g_string_printf GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_string_printf)
296#define g_string_sprintfa g_string_append_printf GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_string_append_printf)
297
298G_END_DECLS
299
300#endif /* __G_STRING_H__ */
301