wcstok Subroutine

Purpose

Converts wide-character strings to tokens.

Library

Standard C Library (libc.a)

Syntax

#include <wchar.h>

wchar_t *wcstok ( WcString1 WcString2,  ptr)
wchar_t *WcString1;
const wchar_t *WcString2;
wchar_t **ptr

Description

A sequence of calls to the wcstok subroutine breaks the wide-character string pointed to by WcString1 into a sequence of tokens, each of which is delimited by a wide-character code from the wide-character string pointed to by WcString2. The third argument points to a caller-provided wchar_t pointer where wcstok stores information necessary for it to continue scanning the same wide-character string.

The first call in the sequence has WcString1 as its first argument and is followed by calls with a nullpointer as their first argument. The separator string pointed to by WcString2 may be different from call to call.

The first call in the sequence searches the wide-character string pointed to by WcString1 for the first wide-character code that is not contained in the current separator string pointed to by WcString2. If no such wide-character code is found, then there are no tokens in the wide-character string pointed to by WcString1 and wcstok returns a null pointer. If such a wide-character code is found, it is the start of the first token.

The wcstok subroutine then searches from there for a wide-character code that is contained in the current separator string. If no such wide-character code is found, the current token extends to the end of the wide-character string pointed to by WcString1, and subsequent searches for a token returns a null pointer. If such a wide-character code is found, it is overwritten by a null wide-character, which terminates the current token. The wcstok subroutine saves a pointer to the following wide-character code, from which the next search for a token starts.

Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.

The implementation behaves as if no function calls wcstok.

Parameters

Item Description
ptr Contains a pointer to a caller-provided wchar_t pointer where wcstok stores information necessary for it to continue scanning the same wide-character string.
WcString1 Contains a pointer to the wide-character string to be searched.
WcString2 Contains a pointer to the string of wide-character token delimiters.

Return Values

Upon successful completion, wcstok returns a pointer to the first wide-character code of a token. Otherwise, if there is no token, wcstok returns a null pointer.

Examples

To convert a wide-character string to tokens, use the following:

#include <wchar.h>
#include <locale.h>
#include <stdlib.h>

 
main()
{
        wchar_t WCString1[] = L"?a???b,,,#c";
        wchar_t *ptr;
        wchar_t *pwcs;

 
        (void)setlocale(LC_ALL, "");
        pwcs = wcstok(WCString1, L"?", &ptr);
                /* pwcs points to the token L"a"*/
        pwcs = wcstok((wchar_t *)NULL, L",", &ptr);
                /* pwcs points to the token L"??b"*/
        pwcs = wcstok( (wchar_t *)NULL, L"#,", &ptr);
                /* pwcs points to the token L"c"*/

}