glib-2.0/glib/gstrfuncs.h

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019
0020 /*
0021  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
0022  * file for a list of people on the GLib Team.  See the ChangeLog
0023  * files for a list of changes.  These files are distributed with
0024  * GLib at ftp://ftp.gtk.org/pub/gtk/.
0025  */
0026
0027 #ifndef __G_STRFUNCS_H__
0028 #define __G_STRFUNCS_H__
0029
0030 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0031 #error "Only <glib.h> can be included directly."
0032 #endif
0033
0034 #include <stdarg.h>
0035 #include <string.h>
0036
0037 #include <glib/gmacros.h>
0038 #include <glib/gtypes.h>
0039 #include <glib/gerror.h>
0040 #include <glib/gmem.h>
0041
0042 G_BEGIN_DECLS
0043
0044 /* Functions like the ones in <ctype.h> that are not affected by locale. */
0045 typedef enum {
0046   G_ASCII_ALNUM  = 1 << 0,
0047   G_ASCII_ALPHA  = 1 << 1,
0048   G_ASCII_CNTRL  = 1 << 2,
0049   G_ASCII_DIGIT  = 1 << 3,
0050   G_ASCII_GRAPH  = 1 << 4,
0051   G_ASCII_LOWER  = 1 << 5,
0052   G_ASCII_PRINT  = 1 << 6,
0053   G_ASCII_PUNCT  = 1 << 7,
0054   G_ASCII_SPACE  = 1 << 8,
0055   G_ASCII_UPPER  = 1 << 9,
0056   G_ASCII_XDIGIT = 1 << 10
0057 } GAsciiType;
0058
0059 GLIB_VAR const guint16 * const g_ascii_table;
0060
0061 #define g_ascii_isalnum(c) \
0062   ((g_ascii_table[(guchar) (c)] & G_ASCII_ALNUM) != 0)
0063
0064 #define g_ascii_isalpha(c) \
0065   ((g_ascii_table[(guchar) (c)] & G_ASCII_ALPHA) != 0)
0066
0067 #define g_ascii_iscntrl(c) \
0068   ((g_ascii_table[(guchar) (c)] & G_ASCII_CNTRL) != 0)
0069
0070 #define g_ascii_isdigit(c) \
0071   ((g_ascii_table[(guchar) (c)] & G_ASCII_DIGIT) != 0)
0072
0073 #define g_ascii_isgraph(c) \
0074   ((g_ascii_table[(guchar) (c)] & G_ASCII_GRAPH) != 0)
0075
0076 #define g_ascii_islower(c) \
0077   ((g_ascii_table[(guchar) (c)] & G_ASCII_LOWER) != 0)
0078
0079 #define g_ascii_isprint(c) \
0080   ((g_ascii_table[(guchar) (c)] & G_ASCII_PRINT) != 0)
0081
0082 #define g_ascii_ispunct(c) \
0083   ((g_ascii_table[(guchar) (c)] & G_ASCII_PUNCT) != 0)
0084
0085 #define g_ascii_isspace(c) \
0086   ((g_ascii_table[(guchar) (c)] & G_ASCII_SPACE) != 0)
0087
0088 #define g_ascii_isupper(c) \
0089   ((g_ascii_table[(guchar) (c)] & G_ASCII_UPPER) != 0)
0090
0091 #define g_ascii_isxdigit(c) \
0092   ((g_ascii_table[(guchar) (c)] & G_ASCII_XDIGIT) != 0)
0093
0094 GLIB_AVAILABLE_IN_ALL
0095 gchar                 g_ascii_tolower  (gchar        c) G_GNUC_CONST;
0096 GLIB_AVAILABLE_IN_ALL
0097 gchar                 g_ascii_toupper  (gchar        c) G_GNUC_CONST;
0098
0099 GLIB_AVAILABLE_IN_ALL
0100 gint                  g_ascii_digit_value  (gchar    c) G_GNUC_CONST;
0101 GLIB_AVAILABLE_IN_ALL
0102 gint                  g_ascii_xdigit_value (gchar    c) G_GNUC_CONST;
0103
0104 /* String utility functions that modify a string argument or
0105  * return a constant string that must not be freed.
0106  */
0107 #define  G_STR_DELIMITERS   "_-|> <."
0108 GLIB_AVAILABLE_IN_ALL
0109 gchar*                g_strdelimit     (gchar        *string,
0110                     const gchar  *delimiters,
0111                     gchar         new_delimiter);
0112 GLIB_AVAILABLE_IN_ALL
0113 gchar*                g_strcanon       (gchar        *string,
0114                     const gchar  *valid_chars,
0115                     gchar         substitutor);
0116 GLIB_AVAILABLE_IN_ALL
0117 const gchar *         g_strerror       (gint          errnum) G_GNUC_CONST;
0118 GLIB_AVAILABLE_IN_ALL
0119 const gchar *         g_strsignal      (gint          signum) G_GNUC_CONST;
0120 GLIB_AVAILABLE_IN_ALL
0121 gchar *               g_strreverse     (gchar        *string);
0122 GLIB_AVAILABLE_IN_ALL
0123 gsize                 g_strlcpy        (gchar        *dest,
0124                     const gchar  *src,
0125                     gsize         dest_size);
0126 GLIB_AVAILABLE_IN_ALL
0127 gsize                 g_strlcat        (gchar        *dest,
0128                     const gchar  *src,
0129                     gsize         dest_size);
0130 GLIB_AVAILABLE_IN_ALL
0131 gchar *               g_strstr_len     (const gchar  *haystack,
0132                     gssize        haystack_len,
0133                     const gchar  *needle);
0134 GLIB_AVAILABLE_IN_ALL
0135 gchar *               g_strrstr        (const gchar  *haystack,
0136                     const gchar  *needle);
0137 GLIB_AVAILABLE_IN_ALL
0138 gchar *               g_strrstr_len    (const gchar  *haystack,
0139                     gssize        haystack_len,
0140                     const gchar  *needle);
0141
0142 GLIB_AVAILABLE_IN_ALL
0143 gboolean             (g_str_has_suffix) (const gchar *str,
0144                                          const gchar *suffix);
0145 GLIB_AVAILABLE_IN_ALL
0146 gboolean             (g_str_has_prefix) (const gchar *str,
0147                                          const gchar *prefix);
0148
0149 #if G_GNUC_CHECK_VERSION (2, 0)
0150 #ifndef __GTK_DOC_IGNORE__
0151 #ifndef __GI_SCANNER__
0152
0153 /* This macro is defeat a false -Wnonnull warning in GCC.
0154  * Without it, it thinks strlen and memcmp may be getting passed NULL
0155  * despite the explicit check for NULL right above the calls.
0156  */
0157 #define _G_STR_NONNULL(x) ((x) + !(x))
0158
0159 #define g_str_has_prefix(STR, PREFIX)                                         \
0160   (__builtin_constant_p (PREFIX)?                                             \
0161     G_GNUC_EXTENSION ({                                                       \
0162        const char * const __str = (STR);                                      \
0163        const char * const __prefix = (PREFIX);                                \
0164        gboolean __result = FALSE;                                             \
0165                                                                               \
0166        if G_UNLIKELY (__str == NULL || __prefix == NULL)                      \
0167            __result = (g_str_has_prefix) (__str, __prefix);                   \
0168        else                                                                   \
0169          {                                                                    \
0170             const size_t __str_len = strlen (_G_STR_NONNULL (__str));         \
0171             const size_t __prefix_len = strlen (_G_STR_NONNULL (__prefix));   \
0172             if (__str_len >= __prefix_len)                                    \
0173               __result = memcmp (_G_STR_NONNULL (__str),                      \
0174                                  _G_STR_NONNULL (__prefix),                   \
0175                                  __prefix_len) == 0;                          \
0176          }                                                                    \
0177          __result;                                                            \
0178     })                                                                        \
0179   :                                                                           \
0180     (g_str_has_prefix) (STR, PREFIX)                                          \
0181   )
0182
0183 #define g_str_has_suffix(STR, SUFFIX)                                         \
0184   (__builtin_constant_p (SUFFIX)?                                             \
0185     G_GNUC_EXTENSION ({                                                       \
0186        const char * const __str = (STR);                                      \
0187        const char * const __suffix = (SUFFIX);                                \
0188        gboolean __result = FALSE;                                             \
0189                                                                               \
0190        if G_UNLIKELY (__str == NULL || __suffix == NULL)                      \
0191          __result = (g_str_has_suffix) (__str, __suffix);                     \
0192        else                                                                   \
0193          {                                                                    \
0194             const size_t __str_len = strlen (_G_STR_NONNULL (__str));         \
0195             const size_t __suffix_len = strlen (_G_STR_NONNULL (__suffix));   \
0196             if (__str_len >= __suffix_len)                                    \
0197               __result = memcmp (__str + __str_len - __suffix_len,            \
0198                                  _G_STR_NONNULL (__suffix),                   \
0199                                  __suffix_len) == 0;                          \
0200          }                                                                    \
0201          __result;                                                            \
0202     })                                                                        \
0203   :                                                                           \
0204     (g_str_has_suffix) (STR, SUFFIX)                                          \
0205   )
0206
0207 #endif /* !defined (__GI_SCANNER__) */
0208 #endif /* !defined (__GTK_DOC_IGNORE__) */
0209 #endif /* G_GNUC_CHECK_VERSION (2, 0) */
0210
0211 /* String to/from double conversion functions */
0212
0213 GLIB_AVAILABLE_IN_ALL
0214 gdouble               g_strtod         (const gchar  *nptr,
0215                     gchar       **endptr);
0216 GLIB_AVAILABLE_IN_ALL
0217 gdouble               g_ascii_strtod   (const gchar  *nptr,
0218                     gchar       **endptr);
0219 GLIB_AVAILABLE_IN_ALL
0220 guint64           g_ascii_strtoull (const gchar *nptr,
0221                     gchar      **endptr,
0222                     guint        base);
0223 GLIB_AVAILABLE_IN_ALL
0224 gint64            g_ascii_strtoll  (const gchar *nptr,
0225                     gchar      **endptr,
0226                     guint        base);
0227 /* 29 bytes should enough for all possible values that
0228  * g_ascii_dtostr can produce.
0229  * Then add 10 for good measure */
0230 #define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
0231 GLIB_AVAILABLE_IN_ALL
0232 gchar *               g_ascii_dtostr   (gchar        *buffer,
0233                     gint          buf_len,
0234                     gdouble       d);
0235 GLIB_AVAILABLE_IN_ALL
0236 gchar *               g_ascii_formatd  (gchar        *buffer,
0237                     gint          buf_len,
0238                     const gchar  *format,
0239                     gdouble       d);
0240
0241 /* removes leading spaces */
0242 GLIB_AVAILABLE_IN_ALL
0243 gchar*                g_strchug        (gchar        *string);
0244 /* removes trailing spaces */
0245 GLIB_AVAILABLE_IN_ALL
0246 gchar*                g_strchomp       (gchar        *string);
0247 /* removes leading & trailing spaces */
0248 #define g_strstrip( string )    g_strchomp (g_strchug (string))
0249
0250 GLIB_AVAILABLE_IN_ALL
0251 gint                  g_ascii_strcasecmp  (const gchar *s1,
0252                        const gchar *s2);
0253 GLIB_AVAILABLE_IN_ALL
0254 gint                  g_ascii_strncasecmp (const gchar *s1,
0255                        const gchar *s2,
0256                        gsize        n);
0257 GLIB_AVAILABLE_IN_ALL
0258 gchar*                g_ascii_strdown     (const gchar *str,
0259                        gssize       len) G_GNUC_MALLOC;
0260 GLIB_AVAILABLE_IN_ALL
0261 gchar*                g_ascii_strup       (const gchar *str,
0262                        gssize       len) G_GNUC_MALLOC;
0263
0264 GLIB_AVAILABLE_IN_2_40
0265 gboolean              g_str_is_ascii      (const gchar *str);
0266
0267 GLIB_DEPRECATED
0268 gint                  g_strcasecmp     (const gchar *s1,
0269                                         const gchar *s2);
0270 GLIB_DEPRECATED
0271 gint                  g_strncasecmp    (const gchar *s1,
0272                                         const gchar *s2,
0273                                         guint        n);
0274 GLIB_DEPRECATED
0275 gchar*                g_strdown        (gchar       *string);
0276 GLIB_DEPRECATED
0277 gchar*                g_strup          (gchar       *string);
0278
0279
0280 /* String utility functions that return a newly allocated string which
0281  * ought to be freed with g_free from the caller at some point.
0282  */
0283 GLIB_AVAILABLE_IN_ALL
0284 gchar*               (g_strdup)        (const gchar *str) G_GNUC_MALLOC;
0285 GLIB_AVAILABLE_IN_ALL
0286 gchar*                g_strdup_printf  (const gchar *format,
0287                     ...) G_GNUC_PRINTF (1, 2) G_GNUC_MALLOC;
0288 GLIB_AVAILABLE_IN_ALL
0289 gchar*                g_strdup_vprintf (const gchar *format,
0290                     va_list      args) G_GNUC_PRINTF(1, 0) G_GNUC_MALLOC;
0291 GLIB_AVAILABLE_IN_ALL
0292 gchar*                g_strndup        (const gchar *str,
0293                     gsize        n) G_GNUC_MALLOC;
0294 GLIB_AVAILABLE_IN_ALL
0295 gchar*                g_strnfill       (gsize        length,
0296                     gchar        fill_char) G_GNUC_MALLOC;
0297 GLIB_AVAILABLE_IN_ALL
0298 gchar*                g_strconcat      (const gchar *string1,
0299                     ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
0300 GLIB_AVAILABLE_IN_ALL
0301 gchar*                g_strjoin        (const gchar  *separator,
0302                     ...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED;
0303
0304 #if G_GNUC_CHECK_VERSION(2, 0)
0305 #ifndef __GTK_DOC_IGNORE__
0306 #ifndef __GI_SCANNER__
0307
0308 G_ALWAYS_INLINE static inline char *
0309 g_strdup_inline (const char *str)
0310 {
0311   if (__builtin_constant_p (!str) && !str)
0312     return NULL;
0313
0314   if (__builtin_constant_p (!!str) && !!str && __builtin_constant_p (strlen (str)))
0315     {
0316       const size_t len = strlen (str) + 1;
0317       char *dup_str = (char *) g_malloc (len);
0318       return (char *) memcpy (dup_str, str, len);
0319     }
0320
0321   return g_strdup (str);
0322 }
0323
0324 #define g_strdup(x) g_strdup_inline (x)
0325
0326 #endif /* !defined (__GI_SCANNER__) */
0327 #endif /* !defined (__GTK_DOC_IGNORE__) */
0328 #endif /* G_GNUC_CHECK_VERSION (2, 0) */
0329
0330 GLIB_AVAILABLE_IN_ALL
0331 gchar*                g_strcompress    (const gchar *source) G_GNUC_MALLOC;
0332
0333 GLIB_AVAILABLE_IN_ALL
0334 gchar*                g_strescape      (const gchar *source,
0335                     const gchar *exceptions) G_GNUC_MALLOC;
0336
0337 GLIB_DEPRECATED_IN_2_68_FOR (g_memdup2)
0338 gpointer              g_memdup         (gconstpointer mem,
0339                                         guint         byte_size) G_GNUC_ALLOC_SIZE(2);
0340
0341 GLIB_AVAILABLE_IN_2_68
0342 gpointer              g_memdup2        (gconstpointer mem,
0343                                         gsize         byte_size) G_GNUC_ALLOC_SIZE(2);
0344
0345 /* NULL terminated string arrays.
0346  * g_strsplit(), g_strsplit_set() split up string into max_tokens tokens
0347  * at delim and return a newly allocated string array.
0348  * g_strjoinv() concatenates all of str_array's strings, sliding in an
0349  * optional separator, the returned string is newly allocated.
0350  * g_strfreev() frees the array itself and all of its strings.
0351  * g_strdupv() copies a NULL-terminated array of strings
0352  * g_strv_length() returns the length of a NULL-terminated array of strings
0353  */
0354 typedef gchar** GStrv;
0355 GLIB_AVAILABLE_IN_ALL
0356 gchar**               g_strsplit       (const gchar  *string,
0357                     const gchar  *delimiter,
0358                     gint          max_tokens);
0359 GLIB_AVAILABLE_IN_ALL
0360 gchar **          g_strsplit_set   (const gchar *string,
0361                     const gchar *delimiters,
0362                     gint         max_tokens);
0363 GLIB_AVAILABLE_IN_ALL
0364 gchar*                g_strjoinv       (const gchar  *separator,
0365                     gchar       **str_array) G_GNUC_MALLOC;
0366 GLIB_AVAILABLE_IN_ALL
0367 void                  g_strfreev       (gchar       **str_array);
0368 GLIB_AVAILABLE_IN_ALL
0369 gchar**               g_strdupv        (gchar       **str_array);
0370 GLIB_AVAILABLE_IN_ALL
0371 guint                 g_strv_length    (gchar       **str_array);
0372
0373 GLIB_AVAILABLE_IN_ALL
0374 gchar*                g_stpcpy         (gchar        *dest,
0375                                         const char   *src);
0376
0377 GLIB_AVAILABLE_IN_2_40
0378 gchar *                 g_str_to_ascii                                  (const gchar   *str,
0379                                                                          const gchar   *from_locale);
0380
0381 GLIB_AVAILABLE_IN_2_40
0382 gchar **                g_str_tokenize_and_fold                         (const gchar   *string,
0383                                                                          const gchar   *translit_locale,
0384                                                                          gchar       ***ascii_alternates);
0385
0386 GLIB_AVAILABLE_IN_2_40
0387 gboolean                g_str_match_string                              (const gchar   *search_term,
0388                                                                          const gchar   *potential_hit,
0389                                                                          gboolean       accept_alternates);
0390
0391 GLIB_AVAILABLE_IN_2_44
0392 gboolean              g_strv_contains  (const gchar * const *strv,
0393                                         const gchar         *str);
0394
0395 GLIB_AVAILABLE_IN_2_60
0396 gboolean              g_strv_equal     (const gchar * const *strv1,
0397                                         const gchar * const *strv2);
0398
0399 /* Convenience ASCII string to number API */
0400
0401 /**
0402  * GNumberParserError:
0403  * @G_NUMBER_PARSER_ERROR_INVALID: string was not a valid number
0404  * @G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS: string was a number, but out of bounds
0405  *
0406  * Error codes returned by functions converting a string to a number.
0407  *
0408  * Since: 2.54
0409  */
0410 typedef enum
0411   {
0412     G_NUMBER_PARSER_ERROR_INVALID,
0413     G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS,
0414   } GNumberParserError;
0415
0416 /**
0417  * G_NUMBER_PARSER_ERROR:
0418  *
0419  * Domain for errors returned by functions converting a string to a
0420  * number.
0421  *
0422  * Since: 2.54
0423  */
0424 #define G_NUMBER_PARSER_ERROR (g_number_parser_error_quark ())
0425
0426 GLIB_AVAILABLE_IN_2_54
0427 GQuark                g_number_parser_error_quark  (void);
0428
0429 GLIB_AVAILABLE_IN_2_54
0430 gboolean              g_ascii_string_to_signed     (const gchar  *str,
0431                                                     guint         base,
0432                                                     gint64        min,
0433                                                     gint64        max,
0434                                                     gint64       *out_num,
0435                                                     GError      **error);
0436
0437 GLIB_AVAILABLE_IN_2_54
0438 gboolean              g_ascii_string_to_unsigned   (const gchar  *str,
0439                                                     guint         base,
0440                                                     guint64       min,
0441                                                     guint64       max,
0442                                                     guint64      *out_num,
0443                                                     GError      **error);
0444
0445 /**
0446  * g_set_str: (skip)
0447  * @str_pointer: (inout) (not optional) (nullable): a pointer to either
0448  *   a string or `NULL`
0449  * @new_str: (nullable): a string to assign to @str_pointer
0450  *
0451  * Updates a pointer to a string to a copy of @new_str and returns whether the
0452  * string was changed.
0453  *
0454  * If @new_str matches the previous string, this function is a no-op. If
0455  * @new_str is different, a copy of it will be assigned to @str_pointer and
0456  * the previous string pointed to by @str_pointer will be freed with
0457  * [func@GLib.free].
0458  *
0459  * @str_pointer must not be `NULL`, but can point to a `NULL` value.
0460  *
0461  * One convenient usage of this function is in implementing property settings:
0462  * ```C
0463  * void
0464  * foo_set_bar (Foo        *foo,
0465  *              const char *new_bar)
0466  * {
0467  *   g_return_if_fail (IS_FOO (foo));
0468  *
0469  *   if (g_set_str (&foo->bar, new_bar))
0470  *     g_object_notify (foo, "bar");
0471  * }
0472  * ```
0473  *
0474  * Returns: true if the value of @str_pointer changed, false otherwise
0475  *
0476  * Since: 2.76
0477  */
0478 GLIB_AVAILABLE_STATIC_INLINE_IN_2_76
0479 static inline gboolean
0480 g_set_str (char       **str_pointer,
0481            const char  *new_str)
0482 {
0483   char *copy;
0484
0485   if (*str_pointer == new_str ||
0486       (*str_pointer && new_str && strcmp (*str_pointer, new_str) == 0))
0487     return FALSE;
0488
0489   copy = g_strdup (new_str);
0490   g_free (*str_pointer);
0491   *str_pointer = copy;
0492
0493   return TRUE;
0494 }
0495
0496 G_END_DECLS
0497
0498 #endif /* __G_STRFUNCS_H__ */