Namespaces
Variants

wcstok, wcstok_s

From cppreference.net
< c ‎ | string ‎ | wide
C
Strings library
Null-terminated wide strings
Definido en el encabezado <wchar.h>
(1)
wchar_t * wcstok ( wchar_t * str, const wchar_t * delim, wchar_t ** ptr ) ;
(desde C95)
(hasta C99)
wchar_t * wcstok ( wchar_t * restrict str, const wchar_t * restrict delim,
wchar_t ** restrict ptr ) ;
(desde C99)
wchar_t * wcstok_s ( wchar_t * restrict str, rsize_t * restrict strmax,
const wchar_t * restrict delim, wchar_t ** restrict ptr ) ;
(2) (desde C11)
1) Encuentra el siguiente token en una cadena ancha terminada en nulo apuntada por str . Los caracteres separadores son identificados por la cadena ancha terminada en nulo apuntada por delim .
Esta función está diseñada para ser llamada múltiples veces para obtener tokens sucesivos de la misma cadena.
  • Si str ! = NULL , la llamada se trata como la primera llamada a wcstok para esta cadena ancha en particular. La función busca el primer carácter ancho que no está contenido en delim .
  • Si no se encuentra dicho carácter ancho, no hay tokens en str en absoluto, y la función devuelve un puntero nulo.
  • Si se encuentra dicho carácter ancho, es el inicio del token . La función luego busca desde ese punto el primer carácter ancho que sí está contenido en delim .
  • Si no se encuentra dicho carácter ancho, str tiene solo un token, y las llamadas futuras a wcstok devolverán un puntero nulo.
  • Si se encuentra dicho carácter ancho, es reemplazado por el carácter ancho nulo L ' \0 ' y el estado del analizador (normalmente un puntero al siguiente carácter ancho) se almacena en la ubicación proporcionada por el usuario * ptr .
  • La función luego devuelve el puntero al inicio del token.
  • Si str == NULL , la llamada se trata como una llamada posterior a wcstok : la función continúa desde donde se quedó en la invocación anterior con el mismo * ptr . El comportamiento es el mismo que si se pasara como str el puntero al carácter ancho que sigue al último token detectado.
2) Igual que (1) , excepto que en cada paso, escribe el número de caracteres restantes por ver en str en * strmax . Las llamadas repetidas (con str nulo) deben pasar tanto strmax como ptr con los valores almacenados por la llamada anterior. Además, los siguientes errores se detectan en tiempo de ejecución y llaman a la función constraint handler actualmente instalada, sin almacenar nada en el objeto apuntado por ptr
  • strmax , delim , o ptr es un puntero nulo
  • en una llamada no inicial (con str nulo), * ptr es un puntero nulo
  • en la primera llamada, * strmax es cero o mayor que RSIZE_MAX / sizeof ( wchar_t )
  • la búsqueda del final de un token alcanza el final de la cadena fuente (medida por el valor inicial de * strmax ) sin encontrar el terminador nulo
Como todas las funciones con verificación de límites, wcstok_s solo está garantizada que esté disponible si __STDC_LIB_EXT1__ está definido por la implementación y si el usuario define __STDC_WANT_LIB_EXT1__ a la constante entera 1 antes de incluir <wchar.h> .

Contenidos

Parámetros

str - puntero a la cadena ancha terminada en nulo que se va a tokenizar
delim - puntero a la cadena ancha terminada en nulo que identifica los delimitadores
ptr - puntero a un objeto de tipo wchar_t * , que es utilizado tanto por wcstok como por wcstok_s para almacenar el estado interno del analizador
strmax - puntero a un objeto que inicialmente contiene el tamaño de str : wcstok_s almacena el número de caracteres que quedan por examinar

Valor de retorno

Devuelve un puntero al inicio del siguiente token o un puntero nulo si no hay más tokens.

Nota

Esta función es destructiva: escribe los L ' \0 ' caracteres en los elementos de la cadena str . En particular, un literal de cadena ancha no puede usarse como primer argumento de wcstok .

A diferencia de strtok , wcstok no actualiza el almacenamiento estático: almacena el estado del analizador en la ubicación proporcionada por el usuario.

A diferencia de la mayoría de otros tokenizadores, los delimitadores en wcstok pueden ser diferentes para cada token subsiguiente, e incluso pueden depender del contenido de los tokens anteriores.

La implementación de wcstok_s en el Windows CRT es incompatible con el estándar C, es simplemente un alias de wcstok .

Ejemplo

Ejecutar este código 
#include <stdio.h>
#include <wchar.h>
int main(void)
{
    wchar_t input[] = L"A bird came down the walk";
    printf("Parsing the input string '%ls'\n", input);
    wchar_t* buffer;
    wchar_t* token = wcstok(input, L" ", &buffer);
    while (token)
    {
        printf("%ls\n", token);
        token = wcstok(NULL, L" ", &buffer);
    }
    printf("Contents of the input string now: '");
    for (size_t n = 0; n < sizeof input / sizeof *input; ++n)
        input[n] ? printf("%lc", input[n]) : printf("\\0");
    puts("'");
}

Salida: 

Parsing the input string 'A bird came down the walk'
A
bird
came
down
the
walk
Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'

Referencias

  • Estándar C11 (ISO/IEC 9899:2011):
  • 7.29.4.5.7 La función wcstok (p: 437-438)
  • K.3.9.2.3.1 La función wcstok_s (p: 645-646)
  • Estándar C99 (ISO/IEC 9899:1999):
  • 7.24.4.5.7 La función wcstok (p: 383-384)

Véase también

(C11)
encuentra el siguiente token en una cadena de bytes
(función)
Documentación de C++ para wcstok