1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
25 #ifndef __G_STRFUNCS_H__
26 #define __G_STRFUNCS_H__
28 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
29 #error "Only <glib.h> can be included directly."
33 #include <glib/gmacros.h>
34 #include <glib/gtypes.h>
35 #include <glib/gerror.h>
39 /* Functions like the ones in <ctype.h> that are not affected by locale. */
41 G_ASCII_ALNUM = 1 << 0,
42 G_ASCII_ALPHA = 1 << 1,
43 G_ASCII_CNTRL = 1 << 2,
44 G_ASCII_DIGIT = 1 << 3,
45 G_ASCII_GRAPH = 1 << 4,
46 G_ASCII_LOWER = 1 << 5,
47 G_ASCII_PRINT = 1 << 6,
48 G_ASCII_PUNCT = 1 << 7,
49 G_ASCII_SPACE = 1 << 8,
50 G_ASCII_UPPER = 1 << 9,
51 G_ASCII_XDIGIT = 1 << 10
54 GLIB_VAR const guint16 * const g_ascii_table;
56 #define g_ascii_isalnum(c) \
57 ((g_ascii_table[(guchar) (c)] & G_ASCII_ALNUM) != 0)
59 #define g_ascii_isalpha(c) \
60 ((g_ascii_table[(guchar) (c)] & G_ASCII_ALPHA) != 0)
62 #define g_ascii_iscntrl(c) \
63 ((g_ascii_table[(guchar) (c)] & G_ASCII_CNTRL) != 0)
65 #define g_ascii_isdigit(c) \
66 ((g_ascii_table[(guchar) (c)] & G_ASCII_DIGIT) != 0)
68 #define g_ascii_isgraph(c) \
69 ((g_ascii_table[(guchar) (c)] & G_ASCII_GRAPH) != 0)
71 #define g_ascii_islower(c) \
72 ((g_ascii_table[(guchar) (c)] & G_ASCII_LOWER) != 0)
74 #define g_ascii_isprint(c) \
75 ((g_ascii_table[(guchar) (c)] & G_ASCII_PRINT) != 0)
77 #define g_ascii_ispunct(c) \
78 ((g_ascii_table[(guchar) (c)] & G_ASCII_PUNCT) != 0)
80 #define g_ascii_isspace(c) \
81 ((g_ascii_table[(guchar) (c)] & G_ASCII_SPACE) != 0)
83 #define g_ascii_isupper(c) \
84 ((g_ascii_table[(guchar) (c)] & G_ASCII_UPPER) != 0)
86 #define g_ascii_isxdigit(c) \
87 ((g_ascii_table[(guchar) (c)] & G_ASCII_XDIGIT) != 0)
90 gchar g_ascii_tolower (gchar c) G_GNUC_CONST;
92 gchar g_ascii_toupper (gchar c) G_GNUC_CONST;
95 gint g_ascii_digit_value (gchar c) G_GNUC_CONST;
97 gint g_ascii_xdigit_value (gchar c) G_GNUC_CONST;
99 /* String utility functions that modify a string argument or
100 * return a constant string that must not be freed.
102 #define G_STR_DELIMITERS "_-|> <."
103 GLIB_AVAILABLE_IN_ALL
104 gchar* g_strdelimit (gchar *string,
105 const gchar *delimiters,
106 gchar new_delimiter);
107 GLIB_AVAILABLE_IN_ALL
108 gchar* g_strcanon (gchar *string,
109 const gchar *valid_chars,
111 GLIB_AVAILABLE_IN_ALL
112 const gchar * g_strerror (gint errnum) G_GNUC_CONST;
113 GLIB_AVAILABLE_IN_ALL
114 const gchar * g_strsignal (gint signum) G_GNUC_CONST;
115 GLIB_AVAILABLE_IN_ALL
116 gchar * g_strreverse (gchar *string);
117 GLIB_AVAILABLE_IN_ALL
118 gsize g_strlcpy (gchar *dest,
121 GLIB_AVAILABLE_IN_ALL
122 gsize g_strlcat (gchar *dest,
125 GLIB_AVAILABLE_IN_ALL
126 gchar * g_strstr_len (const gchar *haystack,
128 const gchar *needle);
129 GLIB_AVAILABLE_IN_ALL
130 gchar * g_strrstr (const gchar *haystack,
131 const gchar *needle);
132 GLIB_AVAILABLE_IN_ALL
133 gchar * g_strrstr_len (const gchar *haystack,
135 const gchar *needle);
137 GLIB_AVAILABLE_IN_ALL
138 gboolean g_str_has_suffix (const gchar *str,
139 const gchar *suffix);
140 GLIB_AVAILABLE_IN_ALL
141 gboolean g_str_has_prefix (const gchar *str,
142 const gchar *prefix);
144 /* String to/from double conversion functions */
146 GLIB_AVAILABLE_IN_ALL
147 gdouble g_strtod (const gchar *nptr,
149 GLIB_AVAILABLE_IN_ALL
150 gdouble g_ascii_strtod (const gchar *nptr,
152 GLIB_AVAILABLE_IN_ALL
153 guint64 g_ascii_strtoull (const gchar *nptr,
156 GLIB_AVAILABLE_IN_ALL
157 gint64 g_ascii_strtoll (const gchar *nptr,
160 /* 29 bytes should enough for all possible values that
161 * g_ascii_dtostr can produce.
162 * Then add 10 for good measure */
163 #define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
164 GLIB_AVAILABLE_IN_ALL
165 gchar * g_ascii_dtostr (gchar *buffer,
168 GLIB_AVAILABLE_IN_ALL
169 gchar * g_ascii_formatd (gchar *buffer,
174 /* removes leading spaces */
175 GLIB_AVAILABLE_IN_ALL
176 gchar* g_strchug (gchar *string);
177 /* removes trailing spaces */
178 GLIB_AVAILABLE_IN_ALL
179 gchar* g_strchomp (gchar *string);
180 /* removes leading & trailing spaces */
181 #define g_strstrip( string ) g_strchomp (g_strchug (string))
183 GLIB_AVAILABLE_IN_ALL
184 gint g_ascii_strcasecmp (const gchar *s1,
186 GLIB_AVAILABLE_IN_ALL
187 gint g_ascii_strncasecmp (const gchar *s1,
190 GLIB_AVAILABLE_IN_ALL
191 gchar* g_ascii_strdown (const gchar *str,
192 gssize len) G_GNUC_MALLOC;
193 GLIB_AVAILABLE_IN_ALL
194 gchar* g_ascii_strup (const gchar *str,
195 gssize len) G_GNUC_MALLOC;
197 GLIB_AVAILABLE_IN_2_40
198 gboolean g_str_is_ascii (const gchar *str);
201 gint g_strcasecmp (const gchar *s1,
204 gint g_strncasecmp (const gchar *s1,
208 gchar* g_strdown (gchar *string);
210 gchar* g_strup (gchar *string);
213 /* String utility functions that return a newly allocated string which
214 * ought to be freed with g_free from the caller at some point.
216 GLIB_AVAILABLE_IN_ALL
217 gchar* g_strdup (const gchar *str) G_GNUC_MALLOC;
218 GLIB_AVAILABLE_IN_ALL
219 gchar* g_strdup_printf (const gchar *format,
220 ...) G_GNUC_PRINTF (1, 2) G_GNUC_MALLOC;
221 GLIB_AVAILABLE_IN_ALL
222 gchar* g_strdup_vprintf (const gchar *format,
223 va_list args) G_GNUC_PRINTF(1, 0) G_GNUC_MALLOC;
224 GLIB_AVAILABLE_IN_ALL
225 gchar* g_strndup (const gchar *str,
226 gsize n) G_GNUC_MALLOC;
227 GLIB_AVAILABLE_IN_ALL
228 gchar* g_strnfill (gsize length,
229 gchar fill_char) G_GNUC_MALLOC;
230 GLIB_AVAILABLE_IN_ALL
231 gchar* g_strconcat (const gchar *string1,
232 ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
233 GLIB_AVAILABLE_IN_ALL
234 gchar* g_strjoin (const gchar *separator,
235 ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
237 /* Make a copy of a string interpreting C string -style escape
238 * sequences. Inverse of g_strescape. The recognized sequences are \b
239 * \f \n \r \t \\ \" and the octal format.
241 GLIB_AVAILABLE_IN_ALL
242 gchar* g_strcompress (const gchar *source) G_GNUC_MALLOC;
244 /* Copy a string escaping nonprintable characters like in C strings.
245 * Inverse of g_strcompress. The exceptions parameter, if non-NULL, points
246 * to a string containing characters that are not to be escaped.
248 * Deprecated API: gchar* g_strescape (const gchar *source);
249 * Luckily this function wasn't used much, using NULL as second parameter
250 * provides mostly identical semantics.
252 GLIB_AVAILABLE_IN_ALL
253 gchar* g_strescape (const gchar *source,
254 const gchar *exceptions) G_GNUC_MALLOC;
256 GLIB_DEPRECATED_IN_2_68_FOR (g_memdup2)
257 gpointer g_memdup (gconstpointer mem,
258 guint byte_size) G_GNUC_ALLOC_SIZE(2);
260 GLIB_AVAILABLE_IN_2_68
261 gpointer g_memdup2 (gconstpointer mem,
262 gsize byte_size) G_GNUC_ALLOC_SIZE(2);
264 /* NULL terminated string arrays.
265 * g_strsplit(), g_strsplit_set() split up string into max_tokens tokens
266 * at delim and return a newly allocated string array.
267 * g_strjoinv() concatenates all of str_array's strings, sliding in an
268 * optional separator, the returned string is newly allocated.
269 * g_strfreev() frees the array itself and all of its strings.
270 * g_strdupv() copies a NULL-terminated array of strings
271 * g_strv_length() returns the length of a NULL-terminated array of strings
273 typedef gchar** GStrv;
274 GLIB_AVAILABLE_IN_ALL
275 gchar** g_strsplit (const gchar *string,
276 const gchar *delimiter,
278 GLIB_AVAILABLE_IN_ALL
279 gchar ** g_strsplit_set (const gchar *string,
280 const gchar *delimiters,
282 GLIB_AVAILABLE_IN_ALL
283 gchar* g_strjoinv (const gchar *separator,
284 gchar **str_array) G_GNUC_MALLOC;
285 GLIB_AVAILABLE_IN_ALL
286 void g_strfreev (gchar **str_array);
287 GLIB_AVAILABLE_IN_ALL
288 gchar** g_strdupv (gchar **str_array);
289 GLIB_AVAILABLE_IN_ALL
290 guint g_strv_length (gchar **str_array);
292 GLIB_AVAILABLE_IN_ALL
293 gchar* g_stpcpy (gchar *dest,
296 GLIB_AVAILABLE_IN_2_40
297 gchar * g_str_to_ascii (const gchar *str,
298 const gchar *from_locale);
300 GLIB_AVAILABLE_IN_2_40
301 gchar ** g_str_tokenize_and_fold (const gchar *string,
302 const gchar *translit_locale,
303 gchar ***ascii_alternates);
305 GLIB_AVAILABLE_IN_2_40
306 gboolean g_str_match_string (const gchar *search_term,
307 const gchar *potential_hit,
308 gboolean accept_alternates);
310 GLIB_AVAILABLE_IN_2_44
311 gboolean g_strv_contains (const gchar * const *strv,
314 GLIB_AVAILABLE_IN_2_60
315 gboolean g_strv_equal (const gchar * const *strv1,
316 const gchar * const *strv2);
318 /* Convenience ASCII string to number API */
321 * GNumberParserError:
322 * @G_NUMBER_PARSER_ERROR_INVALID: String was not a valid number.
323 * @G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS: String was a number, but out of bounds.
325 * Error codes returned by functions converting a string to a number.
331 G_NUMBER_PARSER_ERROR_INVALID,
332 G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS,
333 } GNumberParserError;
336 * G_NUMBER_PARSER_ERROR:
338 * Domain for errors returned by functions converting a string to a
343 #define G_NUMBER_PARSER_ERROR (g_number_parser_error_quark ())
345 GLIB_AVAILABLE_IN_2_54
346 GQuark g_number_parser_error_quark (void);
348 GLIB_AVAILABLE_IN_2_54
349 gboolean g_ascii_string_to_signed (const gchar *str,
356 GLIB_AVAILABLE_IN_2_54
357 gboolean g_ascii_string_to_unsigned (const gchar *str,
366 #endif /* __G_STRFUNCS_H__ */