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

wcstok requires no supporting OS subroutines.