wcstok, wcstok_s

Определено в заголовке `<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 вообще нет, и функция возвращает указатель null.
Если такой широкий символ найден, он является началом токена. Функция затем ищет с этого момента первый широкий символ, входящий в delim.

Если такой широкий символ не найден, в str содержится только один токен, и последующие вызовы wcstok будут возвращать указатель null
Если такой широкий символ найден, он заменяется нулевым широким символом L'\0' и состояние анализатора (обычно указатель на следующий широкий символ) сохраняется в предоставленном пользователем месте *ptr.

Затем функция возвращает указатель на начало токена.
Если str == NULL, вызов рассматривается как последующий вызов wcstok: функция продолжает с того места, где она остановилась в предыдущем вызове с тем же *ptr. Поведение такое же, как если бы в качестве str был передан указатель на широкий символ, следующий за последним обнаруженным токеном.

2) Аналогично (1), за исключением того, что на каждом шаге записывает количество оставшихся символов для просмотра в str в *strmax. Повторные вызовы (с нулевым str) должны передавать как strmax, так и ptr с значениями, сохранёнными предыдущим вызовом. Кроме того, следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений обработчика ограничений, не сохраняя ничего в объекте, на который указывает ptr:

strmax, delim, или ptr — это указатель null
при повторном вызове (с нулевым str) *ptr — это указатель null
при первом вызове *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 сохраняет количество символов, которые предстоит проверить

Значение возврата

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

Примечание

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

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

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

Пример

#include <wchar.h>
#include <stdio.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)

См. также

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

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/string/wide/wcstok