HELPLIB.HLB  —  CRTL  strtok
    Split strings into tokens.

    Format

      #include  <string.h>

      char *strtok  (char *s1, const char *s2);

      char *strtok_r  (char *s, const char *sep, char **lasts);

1  –  Function Variants

    The strtok function has variants named _strtok32 and _strtok64
    for use with 32-bit and 64-bit pointer sizes, respectively.
    Likewise, the strtok_r function has variants named _strtok_r32
    and _strtok_r64.

2  –  Arguments

 s1

    On the first call, a pointer to a string containing zero or more
    text tokens. On all subsequent calls for that string, a NULL
    pointer.

 s2

    A pointer to a separator string consisting of one or more
    characters. The separator string may differ from call to call.

 s

    A null-terminated string that is a sequence of zero or more text
    tokens separated by spans of one or more characters from the
    separator string sep.

 sep

    A null-terminated string of separator characters. This separator
    string can be different from call to call.

 lasts

    A pointer that points to a user-provided pointer to stored
    information needed for strtok_r to continue scanning the same
    string.

3  –  Description

    The strtok function locates text tokens in a given string. The
    text tokens are delimited by one or more characters from a
    separator string that you specify. The function keeps track of
    its position in the string between calls and, as successive calls
    are made, the function works through the string, identifying the
    text token following the one identified by the previous call.

    A token in s1 starts at the first character that is not a
    character in the separator string s2 and ends either at the end
    of the string or at (but not including) a separator character.

    The first call to the strtok function returns a pointer to the
    first character in the first token and writes a null character
    into s1 immediately following the returned token. Each subsequent
    call (with the value of the first argument remaining NULL)
    returns a pointer to a subsequent token in the string originally
    pointed to by s1. When no tokens remain in the string, the strtok
    function returns a NULL pointer. (This can occur on the first
    call to strtok if the string is empty or contains only separator
    characters.)

    Since strtok inserts null characters into s1 to delimit tokens,
    s1 cannot be a const object.

    The strtok_r function is the reentrant version of strtok. The
    function strtok_r considers the null-terminated string s as a
    sequence of zero or more text tokens separated by spans of one or
    more characters from the separator string sep. The lasts argument
    points to a user-provided pointer to stored information needed
    for strtok_r to continue scanning the same string.

    In the first call to strtok_r, s points to a null-terminated
    string, sep points to a null-terminated string of separator
    characters, and the value pointed to by lasts is ignored. The
    strtok_r function returns a pointer to the first character of
    the first token, writes a null character into s immediately
    following the returned token, and updates the pointer to which
    lasts points.

    In subsequent calls, s is a NULL pointer and lasts is unchanged
    from the previous call so that subsequent calls move through the
    string s, returning successive tokens until no tokens remain. The
    separator string sep can be different from call to call. When no
    token remains in s, a NULL pointer is returned.

4  –  Return Values

    x                  A pointer to the first character of the parsed
                       token in the string.
    NULL               Indicates that there are no tokens remaining
                       in the string.

5  –  Examples

    1.#include <stdio.h>

      #include <string.h>

      main()
      {
          static char str[] = "...ab..cd,,ef.hi";

          printf("|%s|\n", strtok(str, "."));
          printf("|%s|\n", strtok(NULL, ","));
          printf("|%s|\n", strtok(NULL, ",."));
          printf("|%s|\n", strtok(NULL, ",."));
      }

      Running this example program produces the following results:

        $ RUN STRTOK_EXAMPLE1
        |ab|
        |.cd|
        |ef|
        |hi|
        $

    2.#include <stdio.h>

      #include <string.h>

      main()
      {
         char *ptr,
              string[30];

         /* The first character not in the string "-" is "A".  The   */
         /* token ends at "C.                                        */

          strcpy(string, "ABC");
          ptr = strtok(string, "-");
          printf("|%s|\n", ptr);

          /* Returns NULL because no characters not in separator      */
          /* string "-" were found (i.e.  only separator characters   */
          /* were found)                                              */

          strcpy(string, "-");
          ptr = strtok(string, "-");
          if (ptr == NULL)
              printf("ptr is NULL\n");

      }

      Running this example program produces the following results:

        $ RUN STRTOK_EXAMPLE2
        |abc|
        ptr is NULL
        $
Close Help