strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

Статья
06/09/2015

Находит следующий токен в строке, с помощью текущего или переданного языкового стандарта. В этих версиях strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l усовершенствована безопасность, как описано в разделе Функции безопасности в CRT.

Важно!

_mbstok_s и _mbstok_s_l невозможно использовать в приложениях, запускаемых в среде выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

char *strtok_s( 
char *strToken, 
const char *strDelimit,
   char **context 
); 
char *_strtok_s_l( 
char *strToken, 
const char *strDelimit,
   char **context, 
_locale_tlocale 
); 
wchar_t *wcstok_s( 
wchar_t *strToken, 
const wchar_t *strDelimit, 
   wchar_t**context 
); 
wchar_t *_wcstok_s_l( 
wchar_t *strToken, 
const wchar_t *strDelimit, 
   wchar_t**context, 
_locale_tlocale 
); 
unsigned char *_mbstok_s( 
unsigned char*strToken, 
const unsigned char *strDelimit, 
   char **context 
); 
unsigned char *_mbstok_s( 
unsigned char*strToken, 
const unsigned char *strDelimit, 
   char **context, 
_locale_tlocale 
);

Параметры

strToken
Строка, содержащая токен или токены.
strDelimit
Набор разделителей.
context
Используется для хранения данных о положении между вызовами метода strtok_s
locale
Языковой стандарт, который необходимо использовать.

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

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

Условия возникновения ошибки

strToken	strDelimit	context	Возвращаемое значение	errno
NULL	any	указатель на пустой указатель.	NULL	EINVAL
any	NULL	any	NULL	EINVAL
any	any	NULL	NULL	EINVAL

Если strToken равен NULL, но контекст - допустимый указатель на контекст, ошибки нет.

Заметки

Функция strtok_s находит следующий токен в strToken. Набор символов в strDelimit указывает возможные разделители токенов, которые необходимо найти в strToken во время текущего вызова. wcstok_s и _mbstok_sявляются версиями функции strtok_s для расширенных и многобайтовых символов. Аргументы и возвращаемые значения wcstok_s и _wcstok_s_l представляют собой строки расширенных символов; аргументы и возвращаемые значения _mbstok_s и _mbstok_s_l представляют собой строки многобайтовых символов. В остальных случаях эти три функции ведут себя идентично.

Эта функция проверяет свои параметры. Если возникает условие ошибки, которое показано в таблице условий ошибки, вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эти функции устанавливают для errno значение EINVAL и возвращают NULL.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

При первом вызове strtok_s функция пропускает ведущие разделители и возвращает указатель на первый токен в strToken, ставя в конец токена нуль-символ. Из оставшейся части strToken можно выделить больше токенов с помощью серии вызовов strtok_s. Каждый вызов strtok_s изменяет strToken, вставляя нуль-символ после токена, возвращаемого этим вызовом. Указатель context продолжает отслеживать то, какая строка читается и откуда в строку читать следующий токен. Чтобы прочитать следующий токен из strToken, вызовите strtok_s со значением NULL для аргумента strToken и передайте тот же параметр context. Аргумент strToken со значением NULL приводит к тому, что strtok_s ищет следующий токен в измененной strToken. Аргумент strDelimit может принимать любое значение из одного вызова к другому, чтобы набор разделителей мог меняться.

Поскольку параметр context заменяет статические буферы, используемые в strtok и _strtok_l, можно проанализировать две строки одновременно в одном потоке.

Выходное значение зависит от настройки категории LC_CTYPE языкового стандарта; дополнительные сведения см. в разделе setlocale. Версии этих функций без суффикса _l используют текущий языковой стандарт для данной функциональности, зависящей от языкового стандарта; версии с суффиксом _l идентичны, за исключением того, что они используют переданный параметр языкового стандарта. Для получения дополнительной информации см. Языковой стандарт.

Требования

Подпрограмма	Обязательный заголовок
strtok_s	<string.h>
_strtok_s_l	<string.h>
wcstok_s, _wcstok_s_l	<string.h> или <wchar.h>
_mbstok_s, _mbstok_s_l	<mbstring.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

// crt_strtok_s.c
// In this program, a loop uses strtok_s
// to print all the tokens (separated by commas
// or blanks) in two strings at the same time.
//

#include <string.h>
#include <stdio.h>

char string1[] =
    "A string\tof ,,tokens\nand some  more tokens";
char string2[] =
    "Another string\n\tparsed at the same time.";
char seps[]   = " ,\t\n";
char *token1 = NULL;
char *token2 = NULL;
char *next_token1 = NULL;
char *next_token2 = NULL;

int main( void )
{
    printf( "Tokens:\n" );

    // Establish string and get the first token:
    token1 = strtok_s( string1, seps, &next_token1);
    token2 = strtok_s ( string2, seps, &next_token2);

    // While there are tokens in "string1" or "string2"
    while ((token1 != NULL) || (token2 != NULL))
    {
        // Get next token:
        if (token1 != NULL)
        {
            printf( " %s\n", token1 );
            token1 = strtok_s( NULL, seps, &next_token1);
        }
        if (token2 != NULL)
        {
            printf("        %s\n", token2 );
            token2 = strtok_s (NULL, seps, &next_token2);
        }
    }
}