NAME

wcstok, wcstok_r − Split wide-character strings to tokens

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <wchar.h>

wchar_t ∗wcstok(
wchar_t ∗ws1,
const wchar_t ∗ws2);

wchar_t ∗wcstok_r(
wchar_t ∗ws1,
const wchar_t ∗ws2),
wchar_t ∗∗savept);

PARAMETERS

ws1Contains a pointer to the wide-character string to be searched. 

ws2Contains a pointer to the string of wide-character token delimiters. 

saveptIdentifies the location of the wide character where the search for tokens should be started in the next call to wcstok_r(). The savept parameter contains a pointer to a variable that contains a pointer to the wide character in the string. 

DESCRIPTION

The wcstok() function splits the wide-character string pointed to by the ws1 parameter into a sequence of tokens, each of which is delimited by a wide character from the wide-character string pointed to by the ws2 parameter. 

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 parameter 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 have been 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 delimiter 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. 

The wcstok_r() function is the reentrant version of wcstok().  Upon successful completion, the wcstok_r() function stores the saved pointer in ∗savept. . If the s1 parameter is a null pointer, the wcstok_r() function uses the saved pointer in ∗savept to start searching for the next token. 

EXAMPLES

The following example splits 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 )) \
!= NULL) {
            /∗ pwcs points to the first token ∗/
            printf("Token 1 is %S\n", pwcs);
            counter = 2;
            while ((pwcs = wcstok((wchar_t ∗ )NULL, delimiters )) \
!= NULL) {
               printf("Token %d is %S\n", counter, pwcs);
               counter++;
            }
         }
      }
   }
}

RETURN VALUES

Upon successful completion, the wcstok() and wcstok_r() functions return a pointer to the first wide character of a token. A null pointer is returned if there is no token. 

Upon successful completion, the pointer ∗savept is set to the wide character from which the search for the next token starts, or to a null pointer if there is none. 

RELATED INFORMATION

Functions: strtok(3), wcspbrk(3), wcsspn(3), wcstod(3), wcstol(3), wcstoul(3).