wcstok, wcstok_r - Split wide-character strings into
tokens
wchar_t *wcstok(
wchar_t *ws1,
const wchar_t *ws2,
wchar_t **savept );
This prototype conforms to both ISO C and XSH Issue 5 and
is strongly recommended for new applications. The wcstok()
function supported in compilation environments for XSH
versions earlier than XSH Issue 5 does not include the
savept parameter, which is required for threadsafe operation.
The following proprietary prototype is the threadsafe
interface that was supported on Tru64 UNIX versions
prior to Version 4.0 and is supported only to provide
backward compatibility for applications written before the
ISO C and XSH5 threadsafe prototype was available.
wchar_t *wcstok_r(
wchar_t *ws1,
const wchar_t *ws2,
wchar_t **savept );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
wcstok(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Contains a pointer to the wide-character string to be
searched. Contains a pointer to the string of wide-character
token delimiters. 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.
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. It 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 a 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.
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.
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.
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++;
}
}
}
} }
Functions: strtok(3), wcspbrk(3), wcsspn(3), wcstod(3),
wcstol(3), wcstoul(3)
Standards: standards(5)
wcstok(3)
[ Back ] |
