Decorate definitions with info about header file and source.
[kopensolaris-gnu/glibc.git] / manual / string.texi
1 @node String and Array Utilities
2 @chapter String and Array Utilities
3 @pindex <string.h>
4
5 Operations on strings (or arrays of characters) are an important part of
6 many programs.  The GNU C library provides an extensive set of string
7 utility functions, including functions for copying, concatenating,
8 comparing, and searching strings.  Many of these functions can also
9 operate on arbitrary regions of storage; for example, the @code{memcpy}
10 function can be used to copy the contents of any kind of array.  
11
12 While it's fairly common for beginning C programmers to unwittingly
13 ``reinvent the wheel'' by duplicating this functionality in their own
14 code, it pays to become familiar with the library functions and to make
15 use of them, since this offers benefits in maintenance, efficiency, and
16 portability.  For instance, you could easily compare one string to
17 another in two lines of C code.  But if you use the built-in
18 @code{strcmp} function, you're less likely to introduce bugs into your
19 program.  And, since these library functions are typically highly
20 optimized, your program may run faster too.
21
22 @menu
23 * Representation of Strings::   Introduction to basic concepts.
24 * String/Array Conventions::    Whether to use a string function or an
25                                  arbitrary array function.
26 * String Length::               Determining the length of a string.
27 * Copying and Concatenation::   Functions to copy the contents of strings
28                                  and arrays.
29 * String/Array Comparison::     Functions for byte-wise and character-wise
30                                  comparison.
31 * Collation Functions::         Functions for collating strings.
32 * Search Functions::            Searching for a specific element or substring.
33 * Finding Tokens in a String::  Splitting a string into tokens by looking
34                                  for delimiters.
35 @end menu
36
37 @node Representation of Strings
38 @section Representation of Strings
39
40 This section is a quick summary of string concepts for beginning C
41 programmers.  It describes how character strings are represented in C
42 and some common pitfalls.  If you are already familiar with this
43 material, you can skip this section.
44
45 @cindex string
46 @cindex null character
47 A @dfn{string} is an array of @code{char} objects.  Since arrays and
48 pointers are equivalent in C, strings are usually declared to be of type
49 @code{char *}.  By convention, a @dfn{null character}, @code{'\0'},
50 marks the end of a string.  For example, in testing to see whether the
51 @code{char *} @var{p} points to a null character marking the end of a
52 string, you can write @code{!*@var{p}} or @code{*@var{p} == '\0'}.
53
54 A null character is quite different conceptually from a null pointer,
55 although both are equivalent to an integer @code{0} in the appropriate
56 context.
57
58 Declaring a variable of type @code{char *} allocates storage only for a
59 pointer to a string, not for the string itself.  If you declare a string
60 as a @code{char *}, make sure that there is actually a character array
61 allocated for it to point to, and that the pointer is actually
62 initialized to point at the array.  Otherwise, you can get into big
63 trouble by accessing random memory locations.  You can allocate storage
64 for a string either by defining a character array variable, by
65 allocating memory dynamically using a library function like
66 @code{malloc} (@pxref{Unconstrained Allocation}), or by means of a
67 string literal.
68
69 @cindex string literal
70 @dfn{String literals} appear in C program source as strings of
71 characters between double-quote characters (@samp{"}).  In ANSI C,
72 string literals can also be formed by @dfn{string concatenation}:
73 @code{"a" "b"} is the same as @code{"ab"}.  Modification of string
74 literals is not allowed by the GNU C compiler, because literals
75 are placed in read-only storage.
76
77 String variables that are declared to be @code{const} cannot be modified
78 either.  It's generally good style to declare non-modifiable strings to
79 be of type @code{const char *}, since this allows the C compiler to
80 detect accidental modifications as well as providing some amount of
81 documentation about what your program intends to do with the string.
82
83 The amount of memory allocated for the character array may extend past
84 the null character that normally marks the end of the string.  In this
85 document, the term @dfn{allocated size} is carefully used to refer to
86 the total amount of memory allocated for the string, while the term
87 @dfn{length} refers to the number of characters up to (but not including)
88 the terminating null character.
89 @cindex length of string
90 @cindex allocated size of string
91 @cindex size of string
92 @cindex string length
93 @cindex string allocation
94
95 A notorious source of program bugs is trying to put more characters in a
96 string than fit in its allocated size.  When writing code that
97 extends strings or moves characters into a pre-allocated array, you
98 should be very careful to keep track of the size of the array and make
99 explicit checks for overflow.  Many of the library functions @emph{do
100 not} do this for you!  Remember also that you need to allocate an extra
101 byte to hold the null character that marks the end of the string.
102
103 @node String/Array Conventions
104 @section String/Array Conventions
105
106 This chapter describes both functions that work on arbitrary arrays or
107 blocks of memory, and functions that are specific to null-terminated
108 arrays of characters.
109
110 Functions that operate on arbitrary blocks of memory have names
111 beginning with @samp{mem} (such as @code{memcpy}) and invariably take an
112 argument which specifies the size (in bytes) of the block of memory to
113 operate on.  The array arguments and return values for these functions
114 have type @code{void *}, and as a matter of style, the elements of these
115 arrays are referred to as ``bytes''.  You can pass any kind of pointer
116 to these functions, and the @code{sizeof} operator is useful in
117 computing the value for the size argument.
118
119 In contrast, functions that operate specifically on strings have names
120 beginning with @samp{str} (such as @code{strcpy}) and look for a null
121 character to terminate the string instead of requiring an explicit size
122 argument to be passed.  The array arguments and return values for these
123 functions have type @code{char *}, and the array elements are referred
124 to as ``characters''.
125
126 In many cases, there are both @samp{mem} and @samp{str} versions of a
127 function.  The one that is more appropriate to use depends on the exact
128 situation.  When your program is manipulating arbitrary arrays or blocks of
129 storage, then you should always use the @samp{mem} functions.  On the
130 other hand, when you are manipulating null-terminated strings it is
131 usually more convenient to use the @samp{str} functions, unless you
132 already know the length of the string in advance.
133
134 @node String Length
135 @section String Length
136
137 You can get the length of a string using the @code{strlen} function.
138 This function is declared in the header file @file{<string.h>}.
139
140 @comment string.h
141 @comment ANSI
142 @deftypefun size_t strlen (const char *@var{s})
143 The @code{strlen} function returns the length of the null-terminated
144 string @var{s}.  (In other words, it returns the offset of the terminating
145 null character within the array.)
146
147 For example,
148 @example
149 strlen ("hello, world")
150     @result{} 12
151 @end example
152
153 The @code{strlen} function returns the length of a string, not its
154 allocation size.  You can get the allocation size of the character array
155 that holds a string using the @code{sizeof} operator:
156
157 @example
158 char string[32] = "hello, world"; 
159 sizeof (string)
160     @result{} 32
161 strlen (string)
162     @result{} 12
163 @end example
164 @end deftypefun
165
166 @node Copying and Concatenation
167 @section Copying and Concatenation
168
169 You can use the functions described in this section to copy the contents
170 of strings and arrays, or to append the contents of one string to
171 another.  These functions are declared in the header file
172 @file{<string.h>}.
173 @cindex copying strings
174 @cindex string copy functions
175
176 A helpful way to remember the ordering of the arguments to the functions
177 in this section is that it corresponds to an assignment expression, with
178 the destination array specified to the left of the source array.  All
179 of these functions return the address of the destination array.
180
181 Some of these functions might not work properly if the source and
182 destination arrays overlap.  For example, if the beginning of the
183 destination array overlaps the end of the source array, the original
184 contents of that part of the source array may get overwritten before it
185 is copied.  Even worse, in the case of the string functions, the null
186 character marking the end of the string may be lost, and the copy
187 function might get stuck in a loop trashing all the memory allocated to
188 your program.
189
190 Any functions that have problems copying between overlapping arrays are
191 explicitly identified in this manual.  In addition to functions in this
192 section, there are a few others like @code{sprintf} and @code{scanf}.
193
194 @comment string.h
195 @comment ANSI
196 @deftypefun {void *} memcpy (void *@var{to}, const void *@var{from}, size_t @var{size})
197 The @code{memcpy} function copies @var{size} bytes from the object
198 beginning at @var{from} into the object beginning at @var{to}.  The
199 behavior of this function is undefined if the two arrays @var{to} and
200 @var{from} overlap; use @code{memmove} instead if overlapping is possible.
201
202 The value returned by @code{memcpy} is the value of @var{to}.
203
204 Here is an example of how you might use @code{memcpy} to copy the
205 contents of a @code{struct}:
206
207 @example
208 struct foo *old, *new;
209 @dots{}
210 memcpy (new, old, sizeof(struct foo));
211 @end example
212 @end deftypefun
213
214 @comment string.h
215 @comment ANSI
216 @deftypefun {void *} memmove (void *@var{to}, const void *@var{from}, size_t @var{size})
217 The @code{memmove} function is just like @code{memcpy}, except that it works
218 even if the objects @var{to} and @var{from} overlap.  However, since 
219 @code{memmove} needs to make an intermediate copy into a temporary area,
220 it can be less efficient than @code{memcpy}.
221 @end deftypefun
222
223 @comment string.h
224 @comment SVID
225 @deftypefun {void *} memccpy (void *@var{to}, const void *@var{from}, int @var{c}, size_t @var{size})
226 This function copies no more than @var{size} bytes from @var{from} to @var{to},
227 stopping if a byte matching @var{c} is found.  The return value is a pointer
228 into @var{to} one byte past where @var{c} was copied, or a null pointer if
229 no byte matching @var{c} appeared in the first @var{size} bytes of @var{from}.
230 @end deftypefun
231
232 @comment string.h
233 @comment ANSI
234 @deftypefun {void *} memset (void *@var{a}, int @var{c}, size_t @var{size})
235 This function copies the value of @var{c} (converted to an @code{unsigned
236 char}) into each of the first @var{size} bytes of the object beginning at
237 @var{a}.  It returns the value of @var{a}.
238 @end deftypefun
239
240 @comment string.h
241 @comment ANSI
242 @deftypefun {char *} strcpy (char *@var{to}, const char *@var{from})
243 This copies characters from the string @var{from} (up to and including the
244 terminating null character) into the string @var{to}.  Like
245 @code{memcpy}, this function can fail if the strings overlap.  The
246 return value is the value of @var{to}.
247 @end deftypefun
248
249 @comment string.h
250 @comment ANSI
251 @deftypefun {char *} strncpy (char *@var{to}, const char *@var{from}, size_t @var{size})
252 This function is similar to @code{strcpy} except that no more than @var{size}
253 characters are copied.  If the length of @var{from} is less than @var{size} 
254 characters, then the end of @var{to} is filled with null characters until
255 @var{size} characters in all have been written.  
256
257 The behavior is undefined if the strings overlap.
258
259 Unless you know in advance that the length of @var{from} is less than the
260 allocation size of @var{from}, using @code{strncpy} as opposed to
261 @code{strcpy} can avoid bugs relating to writing past the end of a
262 string.
263 @end deftypefun
264
265 @comment string.h
266 @comment SVID
267 @deftypefun {char *} strdup (const char *@var{s})
268 This function copies the null-terminated string @var{s} into a newly
269 allocated (as with @code{malloc}; @pxref{Unconstrained Allocation}
270 string.
271 @end deftypefun
272
273 @comment string.h
274 @comment GNU
275 @deftypefun {char *} stpcpy (char *@var{to}, const char *@var{from})
276 This function is like @code{strcpy}, except that it returns a pointer to
277 the end of the string @var{to} (that is, the address of the terminating
278 null pointer) rather than the beginning.
279 @end deftypefun
280
281 @comment string.h
282 @comment ANSI
283 @deftypefun {char *} strcat (char *@var{to}, const char *@var{from})
284 The @code{strcat} function is similar to @code{strcpy}, except that the
285 characters from @var{from} are concatenated or appended to the end of
286 @var{to}, instead of overwriting it.  That is, the first character from
287 @var{from} overwrites the null character marking the end of @var{to}.  
288
289 This function can fail if the strings overlap.
290 @end deftypefun
291
292 @comment string.h
293 @comment ANSI
294 @deftypefun {char *} strncat (char *@var{to}, const char *@var{from}, size_t @var{size})
295 This function is like @code{strcat} except that not more than @var{size}
296 characters from @var{from} are appended to the end of @var{to}.  A single
297 null character is also always appended to @var{to}, so the total
298 allocated size of @var{to} must be at least @code{@var{size} + 1} bytes
299 longer than its initial length.
300 @end deftypefun
301
302 Here is an example showing the use of @code{strncpy} and @code{strncat}.
303 Notice how, in the call to @code{strncat}, the @var{size} parameter
304 is computed to avoid overflowing the character array @code{buffer}.
305
306 @example
307 #include <string.h>
308 #include <stdio.h>
309
310 #define SIZE 10
311
312 static char buffer[SIZE];
313
314 main ()
315 @{
316   strncpy (buffer, "hello", SIZE);
317   printf ("%s\n", buffer);
318   strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
319   printf ("%s\n", buffer);
320 @}
321 @end example
322
323 @noindent
324 The output produced by this program looks like:
325
326 @example
327 hello
328 hello, wo
329 @end example
330
331 @node String/Array Comparison
332 @section String/Array Comparison
333
334 You can use the functions in this section to perform comparisons on the
335 contents of strings and arrays.  As well as checking for equality, these
336 functions can also be used as the ordering functions for sorting
337 operations.  @xref{Searching and Sorting}, for an example of this.
338
339 Unlike most comparison operations in C, the string comparison functions
340 return a nonzero value if the strings are @emph{not} equivalent rather
341 than if they are.  The sign of the value indicates the relative ordering
342 of the first characters in the strings that are not equivalent:  a
343 negative value indicates that the first string is ``less'' than the
344 second, while a positive value indicates that the first string is 
345 ``greater''.
346 @cindex comparing strings
347 @cindex string comparison
348
349 If you are only interested in using these functions as predicates, you
350 might find it helpful to hide them behind a macro definition, like this:
351
352 @example
353 #define str_eq(s1,s2)  (!strcmp ((s1),(s2)))
354 @end example
355
356 All of these functions are declared in the header file @file{<string.h>}.
357
358 @comment string.h
359 @comment ANSI
360 @deftypefun int memcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size})
361 The function @code{memcmp} compares the @var{size} bytes of memory
362 beginning at @var{a1} against the @var{size} bytes of memory beginning at
363 @var{a1}.  The value returned has the same sign as the difference
364 between the first pair of bytes (interpreted as @code{unsigned
365 char} objects) that differ.
366 @end deftypefun
367
368 On arbitrary arrays, the @code{memcmp} function is mostly useful for
369 testing equality.  It usually isn't meaningful to do byte-wise ordering
370 comparisons on arrays of things other than bytes.  For example, a
371 byte-wise comparison on the bytes that make up floating-point numbers
372 isn't likely to tell you anything about the relationship between the
373 values of the floating-point numbers.
374
375 You should also be careful about using @code{memcmp} to compare objects
376 that can contain ``holes'', such as the padding inserted into structure
377 objects to enforce alignment requirements, extra space at the end of
378 unions, and extra characters at the ends of strings whose length is less
379 than their allocated size.  The contents of these ``holes'' are
380 indeterminate and may cause strange behavior when performing byte-wise
381 comparisons.  In some cases, it may be more appropriate to perform an
382 explicit component-wise comparison.
383
384 For example, given a structure type definition like:
385
386 @example
387 struct foo @{
388   unsigned char tag;
389   union @{
390     double f;
391     long i;
392     char *p;
393     @} value;
394   @};
395 @end example
396
397 @noindent
398 you are better off writing a specialized comparison function to compare
399 @code{struct foo} objects instead of comparing them with @code{memcmp}.
400
401 @comment string.h
402 @comment ANSI
403 @deftypefun int strcmp (const char *@var{s1}, const char *@var{s2})
404 The @code{strcmp} function compares the string @var{s1} against @var{s2},
405 returning a value that has the same sign as the difference between
406 the first pair of characters (interpreted as @code{unsigned char} objects)
407 that are not the same.
408
409 A consequence of the ordering used by @code{strcmp} is that if @var{s1}
410 is an initial substring of @var{s2}, then @var{s1} is considered to be
411 ``less than'' @var{s2}.
412 @end deftypefun
413
414 @comment string.h
415 @comment BSD
416 @deftypefun int strcasecmp (const char *@var{s1}, const char *@var{s2})
417 This function is like @code{strcmp}, except that differences in case
418 are ignored.
419 @end deftypefun
420
421 @comment string.h
422 @comment ANSI
423 @deftypefun int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{size})
424 This function is the similar to @code{strcmp}, except that no more than
425 @var{size} characters are compared.  In other words, if the two strings are
426 the same in their first @var{size} characters, the return value is zero.
427 @end deftypefun
428
429 Here are some examples showing the use of @code{strcmp} and @code{strncmp}.
430 These examples assume the use of the ASCII character set.  (If some
431 other character set --- say, EBCDIC --- is used instead, then the glyphs
432 are associated with different numeric codes, and the return values
433 and ordering may differ.)
434
435 @example
436 strcmp ("hello", "hello")
437     @result{} 0    /* @r{These two strings are the same.} */
438 strcmp ("hello", "Hello")
439     @result{} 32   /* @r{Comparisons are case-sensitive.} */
440 strcmp ("hello", "world")
441     @result{} -15  /* @r{The character @code{'h'} comes before @code{'w'}.} */
442 strcmp ("hello", "hello, world")
443     @result{} -44  /* @r{Comparing a null character against a comma.} */
444 strncmp ("hello", "hello, world"", 5)
445     @result{} 0    /* @r{The initial 5 characters are the same.} */
446 strncmp ("hello, world", "hello, stupid world!!!", 5)
447     @result{} 0    /* @r{The initial 5 characters are the same.} */
448 @end example
449
450
451 @node Collation Functions
452 @section Collation Functions
453
454 @cindex collating strings
455 @cindex string collation
456
457 In some locales, the conventions for lexicographic ordering differ from
458 the strict numeric ordering of character codes.  For example, in Spanish
459 most glyphs with diacritical marks such as accents are not considered
460 distinct letters for the purposes of collation.  On the other hand, the
461 two-character sequence @samp{ll} is treated as a single letter that is
462 collated immediately after @samp{l}.
463
464 You can use the functions @code{strcoll} and @code{strxfrm} (declared in
465 the header file @file{<string.h>}) to compare strings using a collation
466 ordering appropriate for the current locale.  The exact ordering
467 conventions used by these functions are determined by the
468 @code{LC_COLLATE} category; @pxref{Localization}.
469
470 @strong{Incomplete:} I believe that in the standard C locale, the
471 collation sequence for @code{strcoll} is the same as that for
472 @code{strcmp}.  I'm not sure if the ANSI C standard specifies this or
473 if that's just the way we've implemented it.
474
475 Effectively, the way these functions work is by applying a mapping to
476 transform the glyphs in a string to an array of codes that reflects the
477 collation ordering appropriate to the current locale.
478 The function @code{strcoll} performs this mapping implicitly,
479 while @code{strxfrm} can be used to perform the mapping explicitly.  If
480 you are making multiple comparisons using the same string or set of
481 strings, it is likely to be more efficient to use @code{strxfrm} to
482 transform the strings once and then do the comparisons on the
483 transformed strings with @code{strcmp}, instead of passing the
484 untransformed strings to @code{strcoll}.
485
486 @comment string.h
487 @comment ANSI
488 @deftypefun int strcoll (const char *@var{s1}, const char *@var{s2})
489 The @code{strcoll} function is similar to @code{strcmp} but uses the
490 current locale's collation ordering, determined by the @code{LC_COLLATE}
491 category.
492 @end deftypefun
493
494 @comment string.h
495 @comment ANSI
496 @deftypefun size_t strxfrm (char *@var{to}, const char *@var{from}, size_t @var{size})
497 The function @code{strxfrm} applies the collation transformation
498 determined by the @code{LC_COLLATE} category of the current locale to
499 the string @var{from}, and stores the transformed string in @var{to}.  Up
500 to @var{size} characters (including a terminating null character) are
501 stored.  
502
503 The behavior is undefined if the strings @var{to} and @var{from}
504 overlap; @pxref{Copying and Concatenation}.
505
506 The length of the entire transformed string @var{to} is returned.  This
507 value is not affected by the value of @var{size}, and might be more or
508 less than the length of the original string @var{from}.
509
510 If @var{size} is zero, @var{to} is permitted to be a null pointer.  In
511 this case, @code{strxfrm} simply returns the number of characters that
512 would be the length of the transformed string.  This is useful for
513 determining what size string to allocate.
514 @end deftypefun
515
516 The string collation functions are most typically used in conjunction
517 with sorting.  For example, you could use the @code{strcoll} function as
518 the comparison function in conjunction with the @code{qsort} function;
519 @pxref{Searching and Sorting}.  Alternatively, since sorting usually
520 involves doing multiple comparisons, you could set up your data
521 structures so that the key field in the objects being sorted is a 
522 string produced by @code{strxfrm}.
523
524 @strong{Incomplete:} An example is probably appropriate here.
525
526 @strong{Compatibility Note:}  The string collation functions are a new
527 feature of ANSI C.  Older C dialects have no equivalent feature.
528
529 @node Search Functions
530 @section Search Functions
531
532 This section describes library functions which perform various kinds
533 of searching operations on strings and arrays.  These functions are
534 declared in the header file @file{<string.h>}.
535 @cindex searching strings
536 @cindex string search functions
537
538 @comment string.h
539 @comment ANSI
540 @deftypefun {void *} memchr (const void *@var{a}, int @var{c}, size_t @var{size})
541 This function finds the first occurrence of the byte @var{c} (converted to an
542 @code{unsigned char}) in the initial @var{size} bytes of the object beginning
543 at @var{a}.  A pointer to the located byte is returned, or a null pointer
544 if no match was found.
545 @end deftypefun
546
547 @comment string.h
548 @comment ANSI
549 @deftypefun {char *} strchr (const char *@var{s}, int @var{c})
550 The @code{strchr} function finds the first occurrence of the character
551 @var{c} (converted to a @code{char}) in the null-terminated string
552 beginning at @var{s}.  A pointer to the located character is returned, or
553 a null pointer if no match was found.
554
555 For example,
556 @example
557 strchr ("hello, world", 'l')
558     @result{} "llo, world"
559 strchr ("hello, world", '?')
560     @result{} NULL
561 @end example    
562
563 The terminating null character is considered to be part of the string,
564 so you can use this function get a pointer to the end of a string by
565 specifying a null character as the value of the @var{c} argument.
566 @end deftypefun
567
568 @comment string.h
569 @comment ANSI
570 @deftypefun {char *} strrchr (const char *@var{s}, int @var{c})
571 The function @code{strrchr} is like @code{strchr}, except that it searches
572 backwards from the end of the string @var{s} (instead of forwards
573 from the front).
574
575 For example,
576 @example
577 strrchr ("hello, world", 'l')
578     @result{} "ld"
579 @end example
580 @end deftypefun
581
582 @comment string.h
583 @comment ANSI
584 @deftypefun {char *} strstr (const char *@var{s1}, const char *@var{s2})
585 This is like @code{strchr}, except that it searches @var{s1} for a
586 substring @var{s2} rather than just a single character.  It returns a
587 pointer into the string @var{s1} that is the first character of the
588 substring, or a null pointer if no match was found.  If @var{s2} is an
589 empty string, the function returns @var{s1}.
590
591 For example,
592 @example
593 strstr ("hello, world", "l")
594     @result{} "llo, world"
595 strstr ("hello, world", "wo")
596     @result{} "world"
597 @end example
598 @end deftypefun
599
600
601 @comment string.h
602 @comment ANSI
603 @deftypefun size_t strspn (const char *@var{s1}, const char *@var{s2})
604 The @code{strspn} (``string span'') function returns the length of the
605 initial substring of @var{s1} that consists entirely of characters that
606 are members of the set specified by the string @var{s2}.  The order
607 of the characters in @var{s2} is not important.
608
609 For example,
610 @example
611 strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
612     @result{} 5
613 @end example
614 @end deftypefun
615
616 @comment string.h
617 @comment ANSI
618 @deftypefun size_t strcspn (const char *@var{s1}, const char *@var{s2})
619 The @code{strcspn} (``string complement span'') function returns the length
620 of the initial substring of @var{s1} that consists entirely of characters
621 that are @emph{not} members of the set specified by the string @var{s2}.
622 (In other words, it returns the offset of the first character in @var{s1}
623 that is a member of the set @var{s2}.)
624
625 For example,
626 @example
627 strcspn ("hello, world", " \t\n,.;!?")
628     @result{} 5
629 @end example
630 @end deftypefun
631
632 @comment string.h
633 @comment ANSI
634 @deftypefun {char *} strpbrk (const char *@var{s1}, const char *@var{s2})
635 The @code{strpbrk} (``string pointer break'') function is related to
636 @code{strcspn}, except that it returns a pointer to the first character
637 in @var{s1} that is a member of the set @var{s2} instead of the length
638 of the initial substring.  It returns a null pointer if no such character
639 from @var{s2} is found.
640
641 For example,
642 @example
643 strpbrk ("hello, world", " \t\n,.;!?")
644     @result{} ", world"
645 @end example
646 @end deftypefun
647
648 @node Finding Tokens in a String
649 @section Finding Tokens in a String
650
651 @cindex tokenizing strings
652 @cindex breaking a string into tokens
653 @cindex finding tokens in a string
654 It's fairly common for programs to have a need to do some simple kinds
655 of lexical analysis and parsing, such as splitting a command string up
656 into tokens.  You can do this with the @code{strtok} function, declared
657 in the header file @file{<string.h>}.
658
659 @comment string.h
660 @comment ANSI
661 @deftypefun {char *} strtok (char *@var{s1}, const char *@var{s2})
662 A string can be split into tokens by making a series of calls to the
663 function @code{strtok}.
664
665 The string to be split up is passed as the @var{s1} argument on the
666 first call only.  The @code{strtok} function uses this to set up some
667 internal state information.  Subsequent calls to get additional tokens
668 from the same string are indicated by passing a null pointer as the
669 @var{s1} argument.  Calling @code{strtok} with another non-null @var{s1}
670 argument reinitializes the state information.  It is guaranteed that no
671 other library function ever calls @code{strtok} behind your back (which
672 would mess up this internal state information).
673
674 The @var{s2} argument is a string that specifies a set of delimiters
675 that may surround the token being extracted.  All the initial characters
676 that are members of this set are discarded.  The first character that is
677 @emph{not} a member of this set of delimiters marks the beginning of the
678 next token.  The end of the token is found by looking for the next
679 character that is a member of the delimiter set.  This character in the
680 original string @var{s1} is overwritten by a null character, and the
681 pointer to the beginning of the token in @var{s1} is returned.
682
683 On the next call to @code{strtok}, the searching begins at the next
684 character beyond the one that marked the end of the previous token.
685 Note that the set of delimiters @var{s2} do not have to be the same on
686 every call in a series of calls to @code{strtok}.
687
688 If the end of the string @var{s1} is reached, or if the remainder of
689 string consists only of delimiter characters, @code{strtok} returns
690 a null pointer.
691 @end deftypefun
692
693 Here is a simple example showing the use of @code{strtok}.
694
695 @comment Yes, this example has been tested.
696
697 @example
698 #include <string.h>
699 #include <stddef.h>
700
701 @dots{}
702
703 char string[] = "words separated by spaces -- and, punctuation!";
704 const char delimiters[] = " .,;:!-";
705 char *token;
706
707 @dots{}
708
709 token = strtok (string, delimiters);  /* token => "words" */
710 token = strtok (NULL, delimiters);    /* token => "separated" */
711 token = strtok (NULL, delimiters);    /* token => "by" */
712 token = strtok (NULL, delimiters);    /* token => "spaces" */
713 token = strtok (NULL, delimiters);    /* token => "and" */
714 token = strtok (NULL, delimiters);    /* token => "punctuation" */
715 token = strtok (NULL, delimiters);    /* token => NULL */
716 @end example
717
718 Using @code{strtok} is often a bad idea, for two reasons:
719
720 @itemize @bullet
721 @item
722 It's not reentrant.  @xref{Restrictions on Handler Functions}, for
723 a discussion of where and why reentrancy is important.
724
725 @item
726 It won't work if the string is a constant.  For example, in the program
727 above we were very careful to pass it a string variable rather than a
728 string literal.  Even on non-constant strings, the destructive
729 modification of the string by @code{strtok} can cause unexpected
730 behavior if your program has multiple pointers to the same string.
731 To some extent, passing a copy of the string (made with @code{strcpy},
732 for example) can address this problem.
733 @end itemize
734
735