Namespaces
Variants

wcstok, wcstok_s

From cppreference.net
< c ‎ | string ‎ | wide
C
Strings library
Null-terminated wide strings
Определено в заголовочном файле <wchar.h>
(1)
wchar_t * wcstok ( wchar_t * str, const wchar_t * delim, wchar_t ** ptr ) ;
(начиная с C95)
(до C99)
wchar_t * wcstok ( wchar_t * restrict str, const wchar_t * restrict delim,
wchar_t ** restrict ptr ) ;
(начиная с C99)
wchar_t * wcstok_s ( wchar_t * restrict str, rsize_t * restrict strmax,
const wchar_t * restrict delim, wchar_t ** restrict ptr ) ;
(2) (начиная с C11)
1) Находит следующий токен в широкой строке с завершающим нулем, на которую указывает str . Символы-разделители определяются широкой строкой с завершающим нулем, на которую указывает delim .
Эта функция предназначена для многократного вызова для получения последовательных токенов из той же строки.
  • Если str ! = NULL , вызов рассматривается как первый вызов wcstok для данной широкой строки. Функция ищет первый широкий символ, который не содержится в delim .
  • Если такой широкий символ не найден, в str нет токенов, и функция возвращает нулевой указатель.
  • Если такой широкий символ найден, это начало токена . Затем функция ищет с этой точки первый широкий символ, который содержится в delim .
  • Если такой широкий символ не найден, str содержит только один токен, и последующие вызовы wcstok будут возвращать нулевой указатель.
  • Если такой широкий символ найден, он заменяется нулевым широким символом L ' \0 ' , и состояние парсера (обычно указатель на следующий широкий символ) сохраняется в предоставленном пользователем местоположении * ptr .
  • Затем функция возвращает указатель на начало токена.
  • Если str == NULL , вызов рассматривается как последующий вызов wcstok : функция продолжает с места остановки в предыдущем вызове с тем же * ptr . Поведение аналогично тому, как если бы указатель на широкий символ, следующий за последним обнаруженным токеном, был передан как str .
2) То же, что и (1) , за исключением того, что на каждом шаге записывает количество оставшихся символов в str в * strmax . Повторные вызовы (с null str ) должны передавать как strmax , так и ptr со значениями, сохранёнными предыдущим вызовом. Также следующие ошибки обнаруживаются во время выполнения и вызывают установленную в данный момент функцию обработки ограничений , не сохраняя ничего в объекте, на который указывает ptr
  • strmax , delim , или ptr является нулевым указателем
  • при последующих вызовах (с null str ), * ptr является нулевым указателем
  • при первом вызове * strmax равно нулю или превышает RSIZE_MAX / sizeof ( wchar_t )
  • поиск конца токена достигает конца исходной строки (измеряемой начальным значением * strmax ) без обнаружения нулевого терминатора
Как и все функции с проверкой границ, wcstok_s гарантированно доступна только если реализация определяет __STDC_LIB_EXT1__ и если пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 до включения <wchar.h> .

Содержание

Параметры

str - указатель на широкую строку с нулевым завершителем для токенизации
delim - указатель на широкую строку с нулевым завершителем, определяющую разделители
ptr - указатель на объект типа wchar_t * , который используется как wcstok , так и wcstok_s для хранения внутреннего состояния парсера
strmax - указатель на объект, который изначально содержит размер str : wcstok_s сохраняет количество символов, которые осталось обработать

Возвращаемое значение

Возвращает указатель на начало следующей токена или нулевой указатель, если токенов больше нет.

Примечание

Эта функция является деструктивной: она записывает L ' \0 ' символы в элементы строки str . В частности, широкий строковый литерал не может быть использован в качестве первого аргумента функции wcstok .

В отличие от strtok , wcstok не обновляет статическое хранилище: он сохраняет состояние парсера в предоставленном пользователем месте.

В отличие от большинства других токенизаторов, разделители в wcstok могут быть разными для каждого последующего токена и даже могут зависеть от содержимого предыдущих токенов.

Реализация функции wcstok_s в Windows CRT не соответствует стандарту C, являясь лишь псевдонимом для wcstok .

Пример

Запустить этот код 
#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("'");
}

Вывод: 

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'

Ссылки

  • Стандарт C11 (ISO/IEC 9899:2011):
  • 7.29.4.5.7 Функция wcstok (стр. 437-438)
  • K.3.9.2.3.1 Функция wcstok_s (стр. 645-646)
  • Стандарт C99 (ISO/IEC 9899:1999):
  • 7.24.4.5.7 Функция wcstok (стр: 383-384)

Смотрите также

(C11)
находит следующий токен в байтовой строке
(функция)
C++ documentation для wcstok