wcstok(S-osr5)

wcstok -- split wide character string into tokens

Syntax

cc . . . -lc

#include <wchar.h>

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

Description

A wide character string may be treated as consisting of a sequence of text tokens, delimited by special wide-character codes chosen as separators. A sequence of calls to wcstok(S-osr5) breaks the string ws1 into such a sequence of tokens. Any wide-character code from the separator string pointed to by ws2 is a separator. Each token in the string ws1 is delimited by such a separator and is at least one character long. For example, with the separator string "test", the first token in the string "sequence" is "qu" because both characters 's' and 'e' are in the separator string. The only other token in the string "sequence" is "nc". The separator string, however, does not have to be the same in all of the calls.

In the first call in the sequence, all leading separator wide characters in ws1 are skipped, i.e., the string ws1 is scanned until a wide-character code that is not in the current separator string ws2 is found. If the wide character string ws1 consists entirely of wide characters from the separator string, wcstok( ) returns a null pointer, indicating no tokens found in the string ws1. If a non-separator wide-character code is found, it is the start of the first token and the search continues.

From there, wcstok( ) scans the remainder of ws1 for a wide-character code that is in the current separator string, ws2. If not found, the string ws1 has only one token and the start of the first token is the start of the current token. When the next time a token is searched for, a null pointer is returned. If a separator character is found when scanning ws1 for the first token, this separator is overwritten with a null wide character to terminate the current token. A pointer to the following wide-character code is saved by wcstok( ) as the starting point for the next search.

In each subsequent call, set the first argument of wcstok( ) to be null and then the search will start from the pointer saved in the previous call, repeating the process described above.

Return values

If a token is found, wcstok( ) returns a pointer to the first wide character of the token. Otherwise, a null pointer is returned.

Diagnostics

The value of errno is undefined.

Warning

After each call to wcstok( ), a pointer to the start of next possible token is saved and is used in the next call to wcstok( ). This internal state pointer could be upset by a call to a user-defined function if the user-defined function also calls wcstok( ).

This implementation behaves as if no library routines call wcstok( ).

Standards conformance

wcstok is conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.