6.23.51 wcstok Function

Break a wide string into tokens.

Include

<wchar.h>

Prototype

wchar_t * wcschr(wchar_t * restrict s1, const wchar_t * restrict s2, wchar_t ** restrict ptr);

Arguments

s1

the wide string to tokenize

s2

a wide string of characters used as delimiters

ptr

a pointer to a user-supplied pointer used to hold information over subsequent calls to this function

Return Value

Returns the address of the first element that matches the wide string if found; otherwise, returns a null pointer.

Remarks

This function will find the first occurrence of the wide string s2 (excluding the null terminator) within the string s1. If s2 points to a zero length string, s1 is returned.

The address of the wide string to tokenize is passed as the first argument in a tokenizing sequence. Subsequent calls should specify a null pointer as the first argument and the object pointed to by ptr is required to have the value stored by the previous call in the sequence. The wide character string used as the delimiters may be different with each call.

The first call in the sequence searches the wide string pointed to by s1 for the first wide character that is not contained in the wide string pointed to by s2. If no match is found, and a null pointer is returned; otherwise this wide character becomes the start of the first token.

If a wide character from the s2 wide string can be subsequently found from the beginning of this token, it is replaced with a null wide character, thus correctly terminating the token as a wide string. If no such wide character is found, the current token extends to the end of the wide string pointed to by s1.

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

#include <wchar.h>

int main(void)
{
  wchar_t ws[] = L"- This, as they say, is the end.";
  wchar_t * pwc;
  wchar_t * ptr;

  wprintf (L"\"%ls\"  is tokenized:\n", ws);
  pwc = wcstok (ws, L" ,.-", &ptr);
  while (pwc != NULL)
  {
    wprintf (L"%ls\n", pwc);
    pwc = wcstok (NULL, L" ,.-", &ptr);
  }
}

Example Output

"- This, as they say, is the end."  is tokenized:
This
as
they
say
is
the
end