wcstok() — Break a wide-character string into tokens
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C Amendment |
both |
Format
#include <wchar.h>
wchar_t *wcstok(wchar_t * __restrict__wcs1,
const wchar_t * __restrict__wcs2, wchar_t ** __restrict__ptr);#define _XOPEN_SOURCE
#include <wchar.h>
wchar_t *wcstok(wchar_t *wcs1, const wchar_t *wcs2);#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>
wchar_t *wcstok(wchar_t *wcs1,
const wchar_t *wcs2, wchar_t **ptr);General description
A sequence of calls to the wcstok() function breaks the wide string pointed to by wcs1 into a sequence of tokens, each of which is delimited by a wide character from the wide string pointed to by wcs2. The third argument points to a caller-provided wide-character pointer into which the wcstok() function stores information necessary for it to continue scanning the same string.
The first call in the sequence, wcs1 shall point to a wide-character string, while in subsequent calls for the same wide string, wcs1 shall be a NULL pointer. If wcs1 is a NULL pointer, the value pointed to by ptr shall match that set by the previous call for the same wide-character string; otherwise its value is ignored. The separator wide-character string pointed to by wcs2 may be different from call to call.
The first call in the sequence, searches the wide-character string pointed to by wcs1 for the first wide character that is not contained in the current separator wide-character string pointed to by wcs2. If no such wide character is found, then there are no tokens in the wide-character string pointed to by wcs1 and wcstok() returns a NULL pointer. If such a wide character is found, it is the start of the first token.
wcstok() then searches from there for a wide character that is contained in the current separator wide string. If no such wide character is found, the current token extends to the end of the wide-character string pointed to by wcs1, and subsequent searches for a token will return a NULL pointer. If such a wide character is found, it is overwritten by a NULL character, which terminates the current token.
In all cases, the wcstok() function stores sufficient information in the pointer ptr so that subsequent calls, with a NULL pointer as the value of the first argument and the unmodified pointer value as the third, will start searching just past the end of the previously returned token (if any).
The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.
Special behavior for XPG4: If you define any feature test macro specifying XPG4 behavior before the statement in your program source file to include the wchar header, then the compiler assumes that your program is using the XPG4 variety of the wcstok() function, unless you also define the _MSE_PROTOS feature test macro. Please see Table 1 for a list of XPG4 and other feature test macros.
wchar_t *wcstok(wchar_t *wcs1, const wchar_t *wcs2);This variety of the wcstok() function is missing a third parameter to specify the address of restart information in your program storage. Instead, C/370™ provides comparable restart information in runtime library storage. Please note that this library storage is provided on a per thread basis making the XPG4 wcstok() function thread-specific for a threaded application.
Returned value
If successful, wcstok() returns a pointer to the first wide character of a token.
If there is no token, wcstok() returns a NULL pointer.
Example
/* CELEBW22 */
#include <wchar.h>
int main(void)
{
static wchar_t str1[] = L"?a??b,,,#c";
static wchar_t str2[] = L"\t \t";
wchar_t *t, *ptr1, *ptr2;
t = wcstok(str1, L"?", &ptr1); /* t points to the token L"a" */
t = wcstok(NULL, L",", &ptr1); /* t points to the token L"??b" */
t = wcstok(str2, L" \t,", &ptr2); /* t is a null pointer */
t = wcstok(NULL, L"#,", &ptr1); /* t points to the token L"c" */
t = wcstok(NULL, L"?", &ptr1); /* t is a null pointer */
}