lib/string_.h

   1 /* A GNU-like <string.h>.
   2
   3    Copyright (C) 1995-1996, 2001-2007 Free Software Foundation, Inc.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2, or (at your option)
   8    any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software Foundation,
  17    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  18
  19 #ifndef _GL_STRING_H
  20 #define _GL_STRING_H
  21
  22 #include @ABSOLUTE_STRING_H@
  23
  24
  25 /* GL_LINK_WARNING("literal string") arranges to emit the literal string as
  26    a linker warning on most glibc systems.
  27    We use a linker warning rather than a preprocessor warning, because
  28    #warning cannot be used inside macros.  */
  29 #ifndef GL_LINK_WARNING
  30   /* This works on platforms with GNU ld and ELF object format.
  31      Testing __GLIBC__ is sufficient for asserting that GNU ld is in use.
  32      Testing __ELF__ guarantees the ELF object format.
  33      Testing __GNUC__ is necessary for the compound expression syntax.  */
  34 # if defined __GLIBC__ && defined __ELF__ && defined __GNUC__
  35 #  define GL_LINK_WARNING(message) \
  36      GL_LINK_WARNING1 (__FILE__, __LINE__, message)
  37 #  define GL_LINK_WARNING1(file, line, message) \
  38      GL_LINK_WARNING2 (file, line, message)  /* macroexpand file and line */
  39 #  define GL_LINK_WARNING2(file, line, message) \
  40      GL_LINK_WARNING3 (file ":" #line ": warning: " message)
  41 #  define GL_LINK_WARNING3(message) \
  42      ({ static const char warning[sizeof (message)]             \
  43           __attribute__ ((__unused__,                           \
  44                           __section__ (".gnu.warning"),         \
  45                           __aligned__ (1)))                     \
  46           = message "\n";                                       \
  47         (void)0;                                                \
  48      })
  49 # else
  50 #  define GL_LINK_WARNING(message) ((void) 0)
  51 # endif
  52 #endif
  53
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /* Return the first occurrence of NEEDLE in HAYSTACK.  */
  60 #if @GNULIB_MEMMEM@
  61 # if ! @HAVE_DECL_MEMMEM@
  62 extern void *memmem (void const *__haystack, size_t __haystack_len,
  63                      void const *__needle, size_t __needle_len);
  64 # endif
  65 #elif defined GNULIB_POSIXCHECK
  66 # undef memmem
  67 # define memmem(a,al,b,bl) \
  68     (GL_LINK_WARNING ("memmem is unportable - use gnulib module memmem for portability"), \
  69      memmem (a, al, b, bl))
  70 #endif
  71
  72 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
  73    last written byte.  */
  74 #if @GNULIB_MEMPCPY@
  75 # if ! @HAVE_MEMPCPY@
  76 extern void *mempcpy (void *restrict __dest, void const *restrict __src,
  77                       size_t __n);
  78 # endif
  79 #elif defined GNULIB_POSIXCHECK
  80 # undef mempcpy
  81 # define mempcpy(a,b,n) \
  82     (GL_LINK_WARNING ("mempcpy is unportable - use gnulib module mempcpy for portability"), \
  83      mempcpy (a, b, n))
  84 #endif
  85
  86 /* Search backwards through a block for a byte (specified as an int).  */
  87 #if @GNULIB_MEMRCHR@
  88 # if ! @HAVE_DECL_MEMRCHR@
  89 extern void *memrchr (void const *, int, size_t);
  90 # endif
  91 #elif defined GNULIB_POSIXCHECK
  92 # undef memrchr
  93 # define memrchr(a,b,c) \
  94     (GL_LINK_WARNING ("memrchr is unportable - use gnulib module memrchr for portability"), \
  95      memrchr (a, b, c))
  96 #endif
  97
  98 /* Copy SRC to DST, returning the address of the terminating '\0' in DST.  */
  99 #if @GNULIB_STPCPY@
 100 # if ! @HAVE_STPCPY@
 101 extern char *stpcpy (char *restrict __dst, char const *restrict __src);
 102 # endif
 103 #elif defined GNULIB_POSIXCHECK
 104 # undef stpcpy
 105 # define stpcpy(a,b) \
 106     (GL_LINK_WARNING ("stpcpy is unportable - use gnulib module stpcpy for portability"), \
 107      stpcpy (a, b))
 108 #endif
 109
 110 /* Copy no more than N bytes of SRC to DST, returning a pointer past the
 111    last non-NUL byte written into DST.  */
 112 #if @GNULIB_STPNCPY@
 113 # if ! @HAVE_STPNCPY@
 114 #  define stpncpy gnu_stpncpy
 115 extern char *stpncpy (char *restrict __dst, char const *restrict __src,
 116                       size_t __n);
 117 # endif
 118 #elif defined GNULIB_POSIXCHECK
 119 # undef stpncpy
 120 # define stpncpy(a,b,n) \
 121     (GL_LINK_WARNING ("stpncpy is unportable - use gnulib module stpncpy for portability"), \
 122      stpncpy (a, b, n))
 123 #endif
 124
 125 /* Compare strings S1 and S2, ignoring case, returning less than, equal to or
 126    greater than zero if S1 is lexicographically less than, equal to or greater
 127    than S2.
 128    Note: This function does not work in multibyte locales.  */
 129 #if ! @HAVE_STRCASECMP@
 130 extern int strcasecmp (char const *s1, char const *s2);
 131 #endif
 132 #if defined GNULIB_POSIXCHECK
 133 /* strcasecmp() does not work with multibyte strings:
 134    POSIX says that it operates on "strings", and "string" in POSIX is defined
 135    as a sequence of bytes, not of characters.   */
 136 # undef strcasecmp
 137 # define strcasecmp(a,b) \
 138     (GL_LINK_WARNING ("strcasecmp cannot work correctly on character strings in multibyte locales - use mbscasecmp if you care about internationalization, or use c_strcasecmp (from gnulib module c-strcase) if you want a locale independent function"), \
 139      strcasecmp (a, b))
 140 #endif
 141
 142 /* Compare no more than N bytes of strings S1 and S2, ignoring case,
 143    returning less than, equal to or greater than zero if S1 is
 144    lexicographically less than, equal to or greater than S2.
 145    Note: This function cannot work correctly in multibyte locales.  */
 146 #if ! @HAVE_DECL_STRNCASECMP@
 147 extern int strncasecmp (char const *s1, char const *s2, size_t n);
 148 #endif
 149 #if defined GNULIB_POSIXCHECK
 150 /* strncasecmp() does not work with multibyte strings:
 151    POSIX says that it operates on "strings", and "string" in POSIX is defined
 152    as a sequence of bytes, not of characters.  */
 153 # undef strncasecmp
 154 # define strncasecmp(a,b,n) \
 155     (GL_LINK_WARNING ("strncasecmp cannot work correctly on character strings in multibyte locales - use mbsncasecmp or mbspcasecmp if you care about internationalization, or use c_strncasecmp (from gnulib module c-strcase) if you want a locale independent function"), \
 156      strncasecmp (a, b, n))
 157 #endif
 158
 159 #if defined GNULIB_POSIXCHECK
 160 /* strchr() does not work with multibyte strings if the locale encoding is
 161    GB18030 and the character to be searched is a digit.  */
 162 # undef strchr
 163 # define strchr(s,c) \
 164     (GL_LINK_WARNING ("strchr cannot work correctly on character strings in some multibyte locales - use mbschr if you care about internationalization"), \
 165      strchr (s, c))
 166 #endif
 167
 168 /* Find the first occurrence of C in S or the final NUL byte.  */
 169 #if @GNULIB_STRCHRNUL@
 170 # if ! @HAVE_STRCHRNUL@
 171 extern char *strchrnul (char const *__s, int __c_in);
 172 # endif
 173 #elif defined GNULIB_POSIXCHECK
 174 # undef strchrnul
 175 # define strchrnul(a,b) \
 176     (GL_LINK_WARNING ("strchrnul is unportable - use gnulib module strchrnul for portability"), \
 177      strchrnul (a, b))
 178 #endif
 179
 180 /* Duplicate S, returning an identical malloc'd string.  */
 181 #if @GNULIB_STRDUP@
 182 # if ! @HAVE_DECL_STRDUP@ && ! defined strdup
 183 extern char *strdup (char const *__s);
 184 # endif
 185 #elif defined GNULIB_POSIXCHECK
 186 # undef strdup
 187 # define strdup(a) \
 188     (GL_LINK_WARNING ("strdup is unportable - use gnulib module strdup for portability"), \
 189      strdup (a))
 190 #endif
 191
 192 /* Return a newly allocated copy of at most N bytes of STRING.  */
 193 #if @GNULIB_STRNDUP@
 194 # if ! @HAVE_STRNDUP@
 195 #  undef strndup
 196 #  define strndup rpl_strndup
 197 #  if ! @HAVE_DECL_STRNDUP@
 198 extern char *strndup (char const *__string, size_t __n);
 199 #  endif
 200 # endif
 201 #elif defined GNULIB_POSIXCHECK
 202 # undef strndup
 203 # define strndup(a,n) \
 204     (GL_LINK_WARNING ("strndup is unportable - use gnulib module strndup for portability"), \
 205      strndup (a, n))
 206 #endif
 207
 208 /* Find the length (number of bytes) of STRING, but scan at most
 209    MAXLEN bytes.  If no '\0' terminator is found in that many bytes,
 210    return MAXLEN.  */
 211 #if @GNULIB_STRNLEN@
 212 # if ! @HAVE_DECL_STRNLEN@
 213 extern size_t strnlen (char const *__string, size_t __maxlen);
 214 # endif
 215 #elif defined GNULIB_POSIXCHECK
 216 # undef strnlen
 217 # define strnlen(a,n) \
 218     (GL_LINK_WARNING ("strnlen is unportable - use gnulib module strnlen for portability"), \
 219      strnlen (a, n))
 220 #endif
 221
 222 #if defined GNULIB_POSIXCHECK
 223 /* strcspn() assumes the second argument is a list of single-byte characters.
 224    Even in this simple case, it does not work with multibyte strings if the
 225    locale encoding is GB18030 and one of the characters to be searched is a
 226    digit.  */
 227 # undef strcspn
 228 # define strcspn(s,a) \
 229     (GL_LINK_WARNING ("strcspn cannot work correctly on character strings in multibyte locales - use mbscspn if you care about internationalization"), \
 230      strcspn (s, a))
 231 #endif
 232
 233 /* Find the first occurrence in S of any character in ACCEPT.  */
 234 #if @GNULIB_STRPBRK@
 235 # if ! @HAVE_STRPBRK@
 236 extern char *strpbrk (char const *__s, char const *__accept);
 237 # endif
 238 # if defined GNULIB_POSIXCHECK
 239 /* strpbrk() assumes the second argument is a list of single-byte characters.
 240    Even in this simple case, it does not work with multibyte strings if the
 241    locale encoding is GB18030 and one of the characters to be searched is a
 242    digit.  */
 243 #  undef strpbrk
 244 #  define strpbrk(s,a) \
 245      (GL_LINK_WARNING ("strpbrk cannot work correctly on character strings in multibyte locales - use mbspbrk if you care about internationalization"), \
 246       strpbrk (s, a))
 247 # endif
 248 #elif defined GNULIB_POSIXCHECK
 249 # undef strpbrk
 250 # define strpbrk(s,a) \
 251     (GL_LINK_WARNING ("strpbrk is unportable - use gnulib module strpbrk for portability"), \
 252      strpbrk (s, a))
 253 #endif
 254
 255 #if defined GNULIB_POSIXCHECK
 256 /* strspn() assumes the second argument is a list of single-byte characters.
 257    Even in this simple case, it cannot work with multibyte strings.  */
 258 # undef strspn
 259 # define strspn(s,a) \
 260     (GL_LINK_WARNING ("strspn cannot work correctly on character strings in multibyte locales - use mbsspn if you care about internationalization"), \
 261      strspn (s, a))
 262 #endif
 263
 264 #if defined GNULIB_POSIXCHECK
 265 /* strrchr() does not work with multibyte strings if the locale encoding is
 266    GB18030 and the character to be searched is a digit.  */
 267 # undef strrchr
 268 # define strrchr(s,c) \
 269     (GL_LINK_WARNING ("strrchr cannot work correctly on character strings in some multibyte locales - use mbsrchr if you care about internationalization"), \
 270      strrchr (s, c))
 271 #endif
 272
 273 /* Search the next delimiter (char listed in DELIM) starting at *STRINGP.
 274    If one is found, overwrite it with a NUL, and advance *STRINGP
 275    to point to the next char after it.  Otherwise, set *STRINGP to NULL.
 276    If *STRINGP was already NULL, nothing happens.
 277    Return the old value of *STRINGP.
 278
 279    This is a variant of strtok() that is multithread-safe and supports
 280    empty fields.
 281
 282    Caveat: It modifies the original string.
 283    Caveat: These functions cannot be used on constant strings.
 284    Caveat: The identity of the delimiting character is lost.
 285    Caveat: It doesn't work with multibyte strings unless all of the delimiter
 286            characters are ASCII characters < 0x30.
 287
 288    See also strtok_r().  */
 289 #if @GNULIB_STRSEP@
 290 # if ! @HAVE_STRSEP@
 291 extern char *strsep (char **restrict __stringp, char const *restrict __delim);
 292 # endif
 293 # if defined GNULIB_POSIXCHECK
 294 #  undef strsep
 295 #  define strsep(s,d) \
 296      (GL_LINK_WARNING ("strsep cannot work correctly on character strings in multibyte locales - use mbssep if you care about internationalization"), \
 297       strsep (s, d))
 298 # endif
 299 #elif defined GNULIB_POSIXCHECK
 300 # undef strsep
 301 # define strsep(s,d) \
 302     (GL_LINK_WARNING ("strsep is unportable - use gnulib module strsep for portability"), \
 303      strsep (s, d))
 304 #endif
 305
 306 #if defined GNULIB_POSIXCHECK
 307 /* strstr() does not work with multibyte strings if the locale encoding is
 308    different from UTF-8:
 309    POSIX says that it operates on "strings", and "string" in POSIX is defined
 310    as a sequence of bytes, not of characters.  */
 311 # undef strstr
 312 # define strstr(a,b) \
 313     (GL_LINK_WARNING ("strstr cannot work correctly on character strings in most multibyte locales - use mbsstr if you care about internationalization"), \
 314      strstr (a, b))
 315 #endif
 316
 317 /* Find the first occurrence of NEEDLE in HAYSTACK, using case-insensitive
 318    comparison.  */
 319 #if ! @HAVE_STRCASESTR@
 320 extern char *strcasestr (const char *haystack, const char *needle);
 321 #endif
 322 #if defined GNULIB_POSIXCHECK
 323 /* strcasestr() does not work with multibyte strings:
 324    It is a glibc extension, and glibc implements it only for unibyte
 325    locales.  */
 326 # undef strcasestr
 327 # define strcasestr(a,b) \
 328     (GL_LINK_WARNING ("strcasestr does work correctly on character strings in multibyte locales - use mbscasestr if you care about internationalization, or use c-strcasestr if you want a locale independent function"), \
 329      strcasestr (a, b))
 330 #endif
 331
 332 /* Parse S into tokens separated by characters in DELIM.
 333    If S is NULL, the saved pointer in SAVE_PTR is used as
 334    the next starting point.  For example:
 335         char s[] = "-abc-=-def";
 336         char *sp;
 337         x = strtok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
 338         x = strtok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
 339         x = strtok_r(NULL, "=", &sp);   // x = NULL
 340                 // s = "abc\0-def\0"
 341
 342    This is a variant of strtok() that is multithread-safe.
 343
 344    For the POSIX documentation for this function, see:
 345    http://www.opengroup.org/susv3xsh/strtok.html
 346
 347    Caveat: It modifies the original string.
 348    Caveat: These functions cannot be used on constant strings.
 349    Caveat: The identity of the delimiting character is lost.
 350    Caveat: It doesn't work with multibyte strings unless all of the delimiter
 351            characters are ASCII characters < 0x30.
 352
 353    See also strsep().  */
 354 #if @GNULIB_STRTOK_R@
 355 # if ! @HAVE_DECL_STRTOK_R@
 356 extern char *strtok_r (char *restrict s, char const *restrict delim,
 357                        char **restrict save_ptr);
 358 # endif
 359 # if defined GNULIB_POSIXCHECK
 360 #  undef strtok_r
 361 #  define strtok_r(s,d,p) \
 362      (GL_LINK_WARNING ("strtok_r cannot work correctly on character strings in multibyte locales - use mbstok_r if you care about internationalization"), \
 363       strtok_r (s, d, p))
 364 # endif
 365 #elif defined GNULIB_POSIXCHECK
 366 # undef strtok_r
 367 # define strtok_r(s,d,p) \
 368     (GL_LINK_WARNING ("strtok_r is unportable - use gnulib module strtok_r for portability"), \
 369      strtok_r (s, d, p))
 370 #endif
 371
 372
 373 /* The following functions are not specified by POSIX.  They are gnulib
 374    extensions.  */
 375
 376 #if @GNULIB_MBSLEN@
 377 /* Return the number of multibyte characters in the character string STRING.
 378    This considers multibyte characters, unlike strlen, which counts bytes.  */
 379 extern size_t mbslen (const char *string);
 380 #endif
 381
 382 #if @GNULIB_MBSCHR@
 383 /* Locate the first single-byte character C in the character string STRING,
 384    and return a pointer to it.  Return NULL if C is not found in STRING.
 385    Unlike strchr(), this function works correctly in multibyte locales with
 386    encodings such as GB18030.  */
 387 # define mbschr rpl_mbschr /* avoid collision with HP-UX function */
 388 extern char * mbschr (const char *string, int c);
 389 #endif
 390
 391 #if @GNULIB_MBSRCHR@
 392 /* Locate the last single-byte character C in the character string STRING,
 393    and return a pointer to it.  Return NULL if C is not found in STRING.
 394    Unlike strrchr(), this function works correctly in multibyte locales with
 395    encodings such as GB18030.  */
 396 # define mbsrchr rpl_mbsrchr /* avoid collision with HP-UX function */
 397 extern char * mbsrchr (const char *string, int c);
 398 #endif
 399
 400 #if @GNULIB_MBSSTR@
 401 /* Find the first occurrence of the character string NEEDLE in the character
 402    string HAYSTACK.  Return NULL if NEEDLE is not found in HAYSTACK.
 403    Unlike strstr(), this function works correctly in multibyte locales with
 404    encodings different from UTF-8.  */
 405 extern char * mbsstr (const char *haystack, const char *needle);
 406 #endif
 407
 408 #if @GNULIB_MBSCASECMP@
 409 /* Compare the character strings S1 and S2, ignoring case, returning less than,
 410    equal to or greater than zero if S1 is lexicographically less than, equal to
 411    or greater than S2.
 412    Note: This function may, in multibyte locales, return 0 for strings of
 413    different lengths!
 414    Unlike strcasecmp(), this function works correctly in multibyte locales.  */
 415 extern int mbscasecmp (const char *s1, const char *s2);
 416 #endif
 417
 418 #if @GNULIB_MBSNCASECMP@
 419 /* Compare the initial segment of the character string S1 consisting of at most
 420    N characters with the initial segment of the character string S2 consisting
 421    of at most N characters, ignoring case, returning less than, equal to or
 422    greater than zero if the initial segment of S1 is lexicographically less
 423    than, equal to or greater than the initial segment of S2.
 424    Note: This function may, in multibyte locales, return 0 for initial segments
 425    of different lengths!
 426    Unlike strncasecmp(), this function works correctly in multibyte locales.
 427    But beware that N is not a byte count but a character count!  */
 428 extern int mbsncasecmp (const char *s1, const char *s2, size_t n);
 429 #endif
 430
 431 #if @GNULIB_MBSPCASECMP@
 432 /* Compare the initial segment of the character string STRING consisting of
 433    at most mbslen (PREFIX) characters with the character string PREFIX,
 434    ignoring case, returning less than, equal to or greater than zero if this
 435    initial segment is lexicographically less than, equal to or greater than
 436    PREFIX.
 437    Note: This function may, in multibyte locales, return 0 if STRING is of
 438    smaller length than PREFIX!
 439    Unlike strncasecmp(), this function works correctly in multibyte
 440    locales.  */
 441 extern char * mbspcasecmp (const char *string, const char *prefix);
 442 #endif
 443
 444 #if @GNULIB_MBSCASESTR@
 445 /* Find the first occurrence of the character string NEEDLE in the character
 446    string HAYSTACK, using case-insensitive comparison.
 447    Note: This function may, in multibyte locales, return success even if
 448    strlen (haystack) < strlen (needle) !
 449    Unlike strcasestr(), this function works correctly in multibyte locales.  */
 450 extern char * mbscasestr (const char *haystack, const char *needle);
 451 #endif
 452
 453 #if @GNULIB_MBSCSPN@
 454 /* Find the first occurrence in the character string STRING of any character
 455    in the character string ACCEPT.  Return the number of bytes from the
 456    beginning of the string to this occurrence, or to the end of the string
 457    if none exists.
 458    Unlike strcspn(), this function works correctly in multibyte locales.  */
 459 extern size_t mbscspn (const char *string, const char *accept);
 460 #endif
 461
 462 #if @GNULIB_MBSPBRK@
 463 /* Find the first occurrence in the character string STRING of any character
 464    in the character string ACCEPT.  Return the pointer to it, or NULL if none
 465    exists.
 466    Unlike strpbrk(), this function works correctly in multibyte locales.  */
 467 # define mbspbrk rpl_mbspbrk /* avoid collision with HP-UX function */
 468 extern char * mbspbrk (const char *string, const char *accept);
 469 #endif
 470
 471 #if @GNULIB_MBSSPN@
 472 /* Find the first occurrence in the character string STRING of any character
 473    not in the character string REJECT.  Return the number of bytes from the
 474    beginning of the string to this occurrence, or to the end of the string
 475    if none exists.
 476    Unlike strspn(), this function works correctly in multibyte locales.  */
 477 extern size_t mbsspn (const char *string, const char *reject);
 478 #endif
 479
 480 #if @GNULIB_MBSSEP@
 481 /* Search the next delimiter (multibyte character listed in the character
 482    string DELIM) starting at the character string *STRINGP.
 483    If one is found, overwrite it with a NUL, and advance *STRINGP to point
 484    to the next multibyte character after it.  Otherwise, set *STRINGP to NULL.
 485    If *STRINGP was already NULL, nothing happens.
 486    Return the old value of *STRINGP.
 487
 488    This is a variant of mbstok_r() that supports empty fields.
 489
 490    Caveat: It modifies the original string.
 491    Caveat: These functions cannot be used on constant strings.
 492    Caveat: The identity of the delimiting character is lost.
 493
 494    See also mbstok_r().  */
 495 extern char * mbssep (char **stringp, const char *delim);
 496 #endif
 497
 498 #if @GNULIB_MBSTOK_R@
 499 /* Parse the character string STRING into tokens separated by characters in
 500    the character string DELIM.
 501    If STRING is NULL, the saved pointer in SAVE_PTR is used as
 502    the next starting point.  For example:
 503         char s[] = "-abc-=-def";
 504         char *sp;
 505         x = mbstok_r(s, "-", &sp);      // x = "abc", sp = "=-def"
 506         x = mbstok_r(NULL, "-=", &sp);  // x = "def", sp = NULL
 507         x = mbstok_r(NULL, "=", &sp);   // x = NULL
 508                 // s = "abc\0-def\0"
 509
 510    Caveat: It modifies the original string.
 511    Caveat: These functions cannot be used on constant strings.
 512    Caveat: The identity of the delimiting character is lost.
 513
 514    See also mbssep().  */
 515 extern char * mbstok_r (char *string, const char *delim, char **save_ptr);
 516 #endif
 517
 518
 519 #ifdef __cplusplus
 520 }
 521 #endif
 522
 523 #endif