Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

wcstok(3) OSS Library Calls Reference Manual
Usually, the wcstok( ) function is called repeatedly to extract the tokens in a wide-character
string. The first time the application program calls the wcstok( ) function, it sets the ws1 parame-
ter to point to the input wide-character string. The function returns a pointer to the first token.
Then the application program calls the function again with the ws1 parameter set to the null
pointer. This call returns a pointer to the next token in the string. The application program repeats
the call to wcstok( ) with the ws1 parameter set to the null pointer until all the tokens in the string
are returned.
In the initial call to wcstok( ), the function first searches the wide-character string pointed to by
the ws1 parameter to locate the first wide character that does not occur in the wide-character del-
imiter string pointed to by the ws2 parameter. If such a wide character is found, it is the start of
the first token. The wcstok( ) function then searches from there for a wide character that does
occur in the delimiter string. If such a wide-character delimiter is found, wcstok( ) overwrites it
with a null wide character, which terminates the current token. The wcstok( ) function saves a
pointer to the wide character following the null wide character and returns a pointer to the start of
the token.
In the subsequent calls to wcstok( ), in which the ws1 parameter is set to the null pointer, the
function starts at its saved pointer and searches for the next wide character that does not occur in
the wide-character delimiter string pointed to by the ws2 parameter. If such a wide character is
found, it is the start of the new token. The wcstok( ) function then searches from there for a wide
character that does occur in the delimiter string. If such a wide-character delimiter is found,
wcstok( ) overwrites it with a null wide character, which terminates the new token. The wcstok( )
function saves a pointer to the wide character following the null wide character and returns a
pointer to the start of the new token.
If a call to the wcstok( ) function cannot find a wide character that does not occur in the delimiter
string, it returns the null pointer. If a call to the wcstok( ) function cannot find the terminating
wide character that does occur in the delimiter string, the current token extends to the end of the
string and subsequent calls to wcstok( ) will return the null pointer.
If the delimiters used in the wide-character string change from one set of characters to another
within the string, the application program can set the second parameter, ws2, to different wide-
character strings, from call to call.
The implementation behaves as though no function calls the wcstok( ) function.
EXAMPLES
The following example shows how to split a wide-character string into tokens.
#include <wchar.h>
#include <locale.h>
#include <stdio.h>
#define WLENGTH 40
main( )
{
wchar_t WCString1[WLENGTH], delimiters[WLENGTH];
wchar_t * pwcs;
int counter;
(void)setlocale(LC_ALL, "");
printf("Enter the string to be searched: ");
if (fgetws(WCString1, WLENGTH, stdin) != NULL) {
printf("Enter the delimiter(s): ");
if (fgetws(delimiters, WLENGTH, stdin) != NULL) {
if ((pwcs = wcstok(WCString1, delimiters ))
8−34 Hewlett-Packard Company 527187-017