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