wcstok

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)

Arguments

ws1

A pointer to a wide-character string containing 0 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 w_char pointer into which wcstok stores information necessary for it to continue scanning the same wide-character string.

Description

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).

Return Values

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

Example

#include <wchar.h>
#include <string.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",."));
}

Running this example produces the following results:

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