[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

wcstok Subroutine

Purpose

Converts wide character strings to tokens.

Library

Standard C Library (libc.a)

Syntax

#include <string.h>
wchar_t *wcstok (WcString1WcString2)
wchar_t *WcString1;
const wchar_t *WcString2;

Description

Attention: Do not use the wcstok subroutine in a multithreaded environment.

The wcstok subroutine breaks the wide character string pointed to by the WcString1 parameter into a sequence of tokens. Each token is delimited by a wide character from the wide character string that is pointed to by the WcString2 parameter.

Usually, the wcstok subroutine is called several times to extract the tokens in a wide character string. The first time the wcstok subroutine is called, the WcString1 parameter points to the input wide character string. The wide character string pointed to by the WcString1 parameter is searched to locate the first wide character that does not occur in the wide character string pointed to by the WcString2 parameter. If no such wide character is found, the subroutine returns a null pointer. If a wide character is found, it is the start of the first token.

The wcstok subroutine begins searching from that point for a wide character in the current separator string (specified by the WcString2 parameter). If no such wide character is found, the current token extends to the end of the wide character string pointed to by the WcString1 parameter. Subsequent searches for a token return a wide null pointer. If such a wide character separator is found, it is overwritten by a wide character null, which terminates the current token.

The wcstok subroutine saves a pointer to the wide character following the null, from which the next search for a token starts. Each subsequent call has the WcString1 parameter set to a wide character null pointer. The second parameter, WcString2, can be set to different wide character strings.

Parameters

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

The wcstok subroutine returns a pointer to the first wide character of a token. A null pointer is returned if there is no token.

Examples

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

#include <string.h>
#include <locale.h>
#include <stdlib.h>
 
main()
{
        wchar_t *WCString1 = L"?a???b,,,#c";
        wchar_t *pwcs ;
 
        (void)setlocale(LC_ALL, "");
        pwcs = wcstok(WCString1, L"?" ); 
                /* pws points to the token L"a"*/
        pwcs = wcstok((wchar_t *)NULL, L"," ); 
                /* pws points to the token L"??b"*/
        pwcs = wcstok( (wchar_t *)NULL, L"#," );
                /* pws points to the token L"c"*/
}

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The wcschr subroutine, wcscspn subroutine, wcspbrk subroutine, wcsrchr subroutine, wcsspn subroutine, wcstod subroutine, wcstol subroutine, wcstoul subroutine, wcswcs subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character String Search Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]