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 , _strtok_l, , _wcstok_lwcstok, _mbstok, _mbstok_l têm aprimoramentos de strtoksegurança, conforme descrito em Recursos de segurança no CRT.

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.

Valor retornado

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

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 retornados de wcstok_s e _wcstok_s_l são cadeias de caracteres largos. Os argumentos e os valores retornados 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âmetro inválido é invocado, 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 NULL str argumento faz com que strtok_s seja necessário procurar o próximo token no arquivo .str 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, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Requisitos

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