6.27 wcstok—get next token from a string

Synopsis

#include <wchar.h>
wchar_t *wcstok(wchar_t *__restrict source,
    const wchar_t *__restrict delimiters,
    wchar_t **__restrict lasts);

Description
The wcstok function is the wide-character equivalent of the strtok_r function (which in turn is the same as the strtok function with an added argument to make it thread-safe).

The wcstok function is used to isolate (one at a time) sequential tokens in a null-terminated wide-character string, *source. A token is defined as a substring not containing any wide-characters from *delimiters.

The first time that wcstok is called, *source should be specified with the wide-character string to be searched, and *lasts–but not lasts, which must be non-NULL–may be random; subsequent calls, wishing to obtain further tokens from the same string, should pass a null pointer for *source instead but must supply *lasts unchanged from the last call. The separator wide-character string, *delimiters, must be supplied each time and may change between calls. A pointer to placeholder *lasts must be supplied by the caller, and is set each time as needed to save the state by wcstok. Every call to wcstok with *source == NULL must pass the value of *lasts as last set by wcstok.

The wcstok function returns a pointer to the beginning of each subsequent token in the string, after replacing the separator wide-character itself with a null wide-character. When no more tokens remain, a null pointer is returned.

Returns
wcstok returns a pointer to the first wide character of a token, or NULL if there is no token.

Notes
wcstok is thread-safe (unlike strtok, but like strtok_r). wcstok writes into the string being searched.

Portability
wcstok is C99 and POSIX.1-2001.

wcstok requires no supporting OS subroutines.