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