strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, , _mbstok_l

  • Artigo

Localiza o próximo token em uma cadeia de caracteres usando a localidade atual ou uma localidade específica que é informada. Estão disponíveis versões mais seguras dessas funções. Para obter informações, confira strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l.

Importante

_mbstok e _mbstok_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(
   char *strToken,
   const char *strDelimit
);
char *_strtok_l(
   char *strToken,
   const char *strDelimit,
   _locale_t locale
);
wchar_t *wcstok( /* Non-standard, define _CRT_NON_CONFORMING_WCSTOK to use */
   wchar_t *strToken,
   const wchar_t *strDelimit
);
wchar_t *wcstok(
   wchar_t *strToken,
   const wchar_t *strDelimit,
   wchar_t **context
);
wchar_t *_wcstok_l(
   wchar_t *strToken,
   const wchar_t *strDelimit,
   _locale_t locale
);
unsigned char *_mbstok(
   unsigned char *strToken,
   const unsigned char *strDelimit
);
unsigned char *_mbstok_l(
   unsigned char *strToken,
   const unsigned char *strDelimit,
   _locale_t locale
);

Parâmetros

strToken
Cadeia de caracteres que contém o token ou os tokens.

strDelimit
Conjunto de caracteres delimitadores.

locale
Localidade a usar.

context
Aponta para a memória usada para armazenar o estado interno do analisador para que o analisador possa continuar de onde parou na próxima vez que você chamar wcstok.

Valor retornado

Retorna um ponteiro para o próximo token encontrado em strToken. As funções retornam NULL quando já nenhum token é encontrado. Cada chamada modifica strToken substituindo um caractere nulo pelo primeiro delimitador que ocorre após o token retornado.

Comentários

A função strtok localiza o próximo token em strToken. O conjunto de caracteres em strDelimit especifica possíveis delimitadores de token a serem encontrados em strToken na chamada atual. wcstok e _mbstok são versões de caracteres largos e de caracteres multibyte de strtok. Os argumentos e o valor retornado de wcstok são cadeias de caracteres largos. Os argumentos e o valor retornado de são cadeias de _mbstok caracteres multibyte. Caso contrário, essas três funções se comportam de forma idêntica.

A versão de dois argumentos de wcstok não é padrão. Se você precisar usar essa versão, precisará definir _CRT_NON_CONFORMING_WCSTOK antes de #include <wchar.h> (ou #include <string.h>).

Importante

Essas funções acarretam uma ameaça em potencial em relação ao problema de estouro de buffer. Os problemas de estouro de buffer são um método frequente de ataque ao sistema, resultando em uma elevação de privilégio sem garantia. Para obter mais informações, confira Como evitar sobrecargas de buffer.

Na primeira chamada para strtok, a função ignora delimitadores à esquerda e retorna um ponteiro para o primeiro token no strToken, encerrando o token com um caractere nulo. Mais tokens podem ser divididos, fora o restante do strToken por uma série de chamadas para strtok. Cada chamada a strtok modifica strToken inserindo um caractere nulo após o token retornado por essa chamada. Para ler o próximo token de strToken, chame strtok com um valor NULL para o argumento strToken. O NULL strToken argumento faz com que strtok seja necessário procurar o próximo token no arquivo .strToken O argumento strDelimit pode assumir qualquer valor de uma chamada para o próximo, para que o conjunto de delimitadores possa variar.

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 para esse comportamento que depende da localidade. As versões com o sufixo _l são idênticas, com exceção de que, em vez disso, usam o parâmetro de localidade fornecido. Para obter mais informações, consulte Localidade.

Observação

Cada função usa uma variável estática de thread local para classificar a cadeia de caracteres em tokens. Portanto, vários threads simultaneamente podem chamar essas funções sem efeitos indesejáveis. No entanto, em um único thread, chamadas intercaladas para uma dessas funções é tende muito a causar dados corrompidos e resultados imprecisos. Ao classificar cadeias de caracteres diferentes, termine de classificar uma cadeia de caracteres antes de começar a analisar a próxima. Além disso, fique ciente do potencial de risco ao chamar uma dessas funções de dentro de um loop em que outra função seja chamada. Se a outra função acaba usando uma dessas funções, uma sequência intercalada de chamadas resultará, disparando os dados corrompidos.

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

Rotina TCHAR.H _UNICODE e _MBCS não definidos _MBCS definido _UNICODE definido
_tcstok strtok _mbstok wcstok
_tcstok _strtok_l _mbstok_l _wcstok_l

Requisitos

Rotina Cabeçalho necessário
strtok <string.h>
wcstok <string.h> ou <wchar.h>
_wcstok_l <tchar.h>
_mbstok, _mbstok_l <mbstring.h>

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

Exemplo

// crt_strtok.c
// compile with: /W3
// In this program, a loop uses strtok
// to print all the tokens (separated by commas
// or blanks) in the string named "string".
//
#include <string.h>
#include <stdio.h>

char string[] = "A string\tof ,,tokens\nand some  more tokens";
char seps[]   = " ,\t\n";
char *token;

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

   // Establish string and get the first token:
   token = strtok( string, seps ); // C4996
   // Note: strtok is deprecated; consider using strtok_s instead
   while( token != NULL )
   {
      // While there are tokens in "string"
      printf( " %s\n", token );

      // Get next token:
      token = strtok( NULL, seps ); // C4996
   }
}

Tokens:
A
string
of
tokens
and
some
more
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