strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

Localiza o próximo token em uma cadeia de caracteres, usando a localidade atual ou uma localidade específica que é informada. Essas versões do , , , , , _mbstok_ltêm aprimoramentos de segurança, _wcstok_l_mbstok_strtok_lwcstokconforme descrito em Recursos destrtok segurança na CRT.

Importante

_mbstok_s e _mbstok_s_l não podem ser usados em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

char* strtok_s(
   char* str,
   const char* delimiters,
   char** context
);

char* _strtok_s_l(
   char* str,
   const char* delimiters,
   char** context,
   _locale_t locale
);

wchar_t* wcstok_s(
   wchar_t* str,
   const wchar_t* delimiters,
   wchar_t** context
);

wchar_t *_wcstok_s_l(
   wchar_t* str,
   const wchar_t* delimiters,
   wchar_t** context,
   _locale_t locale
);

unsigned char* _mbstok_s(
   unsigned char* str,
   const unsigned char* delimiters,
   char** context
);

unsigned char* _mbstok_s_l(
   unsigned char* str,
   const unsigned char* delimiters,
   char** context,
   _locale_t locale
);

Parâmetros

str
Uma cadeia de caracteres que contém o token ou tokens a serem encontrados.

delimiters
O conjunto de caracteres delimitadores a serem usados.

context
Usado para armazenar informações de posição entre as chamadas para a função.

locale
A localidade a ser usada.

Retornar valor

Retorna um ponteiro para o próximo token encontrado em str. Retorna NULL quando não forem encontrados mais tokens. Cada chamada modifica str substituindo um caractere nulo pelo primeiro delimitador que ocorre após o token retornado.

Condições de erro

str	delimiters	context	Retornar valor	errno
NULL	qualquer	ponteiro para um ponteiro nulo	NULL	EINVAL
qualquer	NULL	qualquer	NULL	EINVAL
qualquer	qualquer	NULL	NULL	EINVAL

Se str é NULL, mas context é um ponteiro para um ponteiro de contexto válido, não há nenhum erro.

Comentários

A família de funções strtok_s localiza o próximo token em str. O conjunto de caracteres em delimiters especifica possíveis delimitadores de token a serem encontrados em str na chamada atual. wcstok_s e _mbstok_s são versões de caracteres largos e de caracteres multibyte de strtok_s. Os argumentos e os valores de retorno de e _wcstok_s_l são cadeias de wcstok_s caracteres largos. Os argumentos e os valores de retorno de e _mbstok_s_l são cadeias de _mbstok_s caracteres multibyte. Caso contrário, essas funções se comportam de forma idêntica.

Essa função valida seus parâmetros. Quando ocorre uma condição de erro, como na tabela Condições de Erro, o manipulador de parâmetros inválido é chamado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão NULL.

Na primeira chamada para strtok_s, a função ignora delimitadores à esquerda e retorna um ponteiro para o primeiro token no str, encerrando o token com um caractere nulo. Mais tokens podem ser divididos, fora o restante do str por uma série de chamadas para strtok_s. Cada chamada para strtok_s modifica str inserindo um caractere nulo após o token retornado pela chamada. O context ponteiro mantém controle de cadeia de caracteres que está sendo lido e no qual o próximo token na cadeia de caracteres deve ser lido. Para ler o próximo token de str, chame strtok_s com um valor NULL para o str argumento e passe o mesmo parâmetro context. O argumento NULLstr faz com que o strtok_s pesquise o próximo token no str modificado. O argumento delimiters pode assumir qualquer valor de uma chamada para o próximo, para que o conjunto de delimitadores possa variar.

Como o parâmetro context substitui os buffers estáticos usados em strtok e _strtok_l, é possível analisar as duas cadeias de caracteres simultaneamente no mesmo thread.

O valor de saída é afetado pela configuração da categoria LC_CTYPE da localidade. Para obter mais informações, consulte setlocale.

As versões dessas funções sem o sufixo _l usam a localidade atual do thread para esse comportamento que depende da localidade. As versões com o sufixo _l são idênticas, exceto que usam a localidade especificada pelo parâmetro locale. Para obter mais informações, consulte Localidade.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

Requisitos

Rotina	Cabeçalho necessário
strtok_s	<string.h>
_strtok_s_l	<string.h>
wcstok_s, _wcstok_s_l	<string.h> ou <wchar.h>
_mbstok_s, _mbstok_s_l	<mbstring.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// 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);
        }
    }
}

Tokens:
A
        Another
string
        string
of
        parsed
tokens
        at
and
        the
some
        same
more
        time.
tokens

Confira também

Manipulação de cadeia de caracteres
Localidade
Interpretação de sequências de caracteres multibyte
strcspn, wcscspn, _mbscspn, _mbscspn_l
strspn, wcsspn, _mbsspn, _mbsspn_l