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