 |
Index for Section 3 |
|
 |
Alphabetical listing for W |
|
wcstok(3)
NAME
wcstok, wcstok_r - Split wide-character strings into tokens
LIBRARY
Standard C Library (libc.so, libc.a)
SYNOPSIS
#include <wchar.h>
wchar_t *wcstok(
wchar_t *ws1,
const wchar_t *ws2);
wchar_t *wcstok(
wchar_t *ws1,
const wchar_t *ws2),
wchar_t **savept);
The wcstok() function that conforms to the XPG4 standard has two parameters
rather than three; the savept parameter, which is required for threadsafe
operation, is included only in the wcstok() function that conforms to the
latest ISO C standard. The following threadsafe interface is supported
only for backward compatibility with Tru64 UNIX versions prior to Version
4.0:
wchar_t *wcstok_r(
wchar_t *ws1,
const wchar_t *ws2),
wchar_t **savept);
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
wcstok(): ISO C, XPG4
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
ws1 Contains a pointer to the wide-character string to be searched.
ws2 Contains a pointer to the string of wide-character token delimiters.
savept
[ISO C] Identifies the location of the wide character where the search
for tokens should be started in the next call. The savept parameter
contains a pointer to a variable that contains a pointer to the wide
character where scanning begins.
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. On the first call to the wcstok() function, the
application sets the ws1 parameter to point to the input wide-character
string. The function returns a pointer to the first token.
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.
On 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 subsequent calls to wcstok(), where ws1 is set to a null pointer, the
function starts at the 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.
[ISO C] On successful completion, the wcstok() function stores the saved
pointer in the *savept parameter as well as internally. On calls where the
s1 parameter is a null pointer, the function uses the saved pointer in
*savept to start searching for the next token. Applications that require
threadsafe operation must use the wcstok() interface that includes the
savept parameter.
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() 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 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.
[Digital] The wcstok_r() function is a reentrant version of wcstok() but
is proprietary; new applications that require standards conformance along
with threadsafe operation should use the wcstok() interface with the savept
parameter rather than the wcstok_r() interface.
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
On successful completion, the wcstok() function returns a pointer to the
first wide character of a token. A null pointer is returned if there is no
token.
[ISO C] The wcstok() function also sets the pointer *savept to the wide
character from which the search for the next token starts, or to a null
pointer if there is none.
[Digital] On successful completion, the wcstok_r() returns a pointer to
the first wide character of a token. A null pointer is returned if there is
no token. The function also sets the pointer *savept 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)
Standards: standards(5)