Locates text tokens in a given wide-character string.

    Format

      #include  <wchar.h>

      wchar_t *wcstok  (wchar_t *ws1, const wchar_t *ws2); (XPG4)

      wchar_t *wcstok  (wchar_t *ws1, const wchar_t *ws2, wchar_t
                       **ptr); (ISO C)

1  –  Function Variants

    The wcstok function has variants named _wcstok32 and _wcstok64
    for use with 32-bit and 64-bit pointer sizes, respectively.

2  –  Arguments

 ws1

    A pointer to a wide-character string containing zero or more text
    tokens.

 ws2

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

 ptr

    ISO C Standard only. Used only when ws1 is NULL, ptr is a caller-
    provided wchar_t pointer into which wcstok stores information
    necessary for it to continue scanning the same wide-character
    string.

3  –  Description

    A sequence of calls to wcstok breaks the wide-character string
    pointed to by ws1 into a sequence of tokens, each of which is
    delimited by a wide character from the wide-character string
    pointed to by ws2.

    The wcstok function keeps track of its position in the wide-
    character string between calls and, as successive calls are made,
    the function works through the wide-character string, identifying
    the text token following the one identified by the previous call.

    Tokens in ws1 are delimited by null characters that wcstok
    inserts into ws1. Therefore, ws1 cannot be a const object.

    The following sections describe differences between the XPG4
    Standard and ISO C Standard interface to wcstok.

    XPG4 Standard Behavior

    The first call to the wcstok function searches the wide-character
    string for the first character that is not found in the separator
    string pointed to by ws2. The first call returns a pointer to the
    first wide character in the first token and writes a null wide
    character into ws1 immediately following the returned token.

    Subsequent calls to wcstok search for a wide character that is
    in the separator string pointed to by ws2. Each subsequent call
    (with the value of the first argument remaining NULL) returns a
    pointer to the next token in the string originally pointed to by
    ws1. When no tokens remain in the string, wcstok returns a NULL
    pointer.

    ISO C Standard Behavior

    For the first call in the sequence, ws1 points to a wide-
    character string. In subsequent calls for the same string, ws1
    is NULL. When ws1 is NULL, the value pointed to by ptr matches
    that stored by the previous call for the same wide-character
    string. Otherwise, the value pointed to by ptr is ignored.

    The first call in the sequence searches the wide-character
    string pointed to by ws1 for the first wide character that is not
    contained in the current separator wide-character string pointed
    to by ws2. If no such wide character is found, then there are no
    tokens in the wide-character string pointed to by ws1, and wcstok
    returns a NULL pointer.

    The wcstok function then searches from there for a wide character
    that is contained in the current separator wide-character string.
    If no such wide character is found, the current token extends
    to the end of the wide-character string pointed to by ws1, and
    subsequent searches in the same wide-character string for a token
    return a NULL pointer. If such a wide character is found, it
    is overwritten by a null wide character, which terminates the
    current token.

    In all cases, wcstok stores sufficient information in the pointer
    pointed to by ptr so that subsequent calls with a NULL pointer
    for ws1 and the unmodified pointer value for ptr start searching
    just past the element overwritten by a null wide character (if
    any).

4  –  Return Values

    x                  A pointer to the first character of a token.
    NULL               Indicates that no token was found.

5  –  Examples

    1./* XPG4 version of wcstok call */

      #include <wchar.h>
      #include <string.h>
      #include <stdio.h>

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

          printf("|%S|\n", wcstok(str, L"."));
          printf("|%S|\n", wcstok(NULL, L","));
          printf("|%S|\n", wcstok(NULL, L",."));
          printf("|%S|\n", wcstok(NULL, L",."));
      }

    2./* ISO C version of wcstok call */

      #include <wchar.h>
      #include <string.h>
      #include <stdio.h>

      main()
      {
          wchar_t str[] = L"...ab..cd,,ef.hi";
          wchar_t *savptr = NULL;

          printf("|%S|\n", wcstok(str, L".", &savptr));
          printf("|%S|\n", wcstok(NULL, L",", &savptr));
          printf("|%S|\n", wcstok(NULL, L",.", &savptr));
          printf("|%S|\n", wcstok(NULL, L",.", &savptr));
      }

    Running this example produces the following results:

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