strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s_mbstok_s_l

Trova il token successivo in una stringa, usando le impostazioni locali correnti o le impostazioni locali passate. Queste versioni di strtok, _strtok_l_wcstok_lwcstok, _mbstok, _mbstok_l includono miglioramenti della sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Sintassi

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

Parametri

str
Stringa contenente il token o i token da trovare.

delimiters
Set di caratteri delimitatori da utilizzare.

context
Consente di archiviare le informazioni sulla posizione tra le chiamate alla funzione.

locale
Impostazioni locali da usare.

Valore restituito

Restituisce un puntatore al successivo token trovato in str. Restituisce NULL quando non vengono trovati altri token. Ogni chiamata modifica str sostituendo un carattere Null per il primo delimitatore che si verifica dopo il token restituito.

Condizioni di errore

Se str è NULL ma context è un puntatore a un puntatore di contesto valido, non viene visualizzato alcun errore.

Osservazioni:

La strtok_s famiglia di funzioni trova il token successivo in str. Il set di caratteri in delimiters specifica i possibili delimitatori del token da trovare in str per la chiamata corrente. wcstok_s e _mbstok_s sono versioni con caratteri wide e caratteri multibyte di strtok_s. Gli argomenti e i valori restituiti di e _wcstok_s_l sono stringhe di wcstok_s caratteri wide. Gli argomenti e i valori restituiti di _mbstok_s e _mbstok_s_l sono stringhe di caratteri multibyte. A parte ciò, queste funzioni si comportano in modo identico.

Questa funzione convalida i relativi parametri. Quando si verifica una condizione di errore, come nella tabella Condizioni di errore, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni impostano errno su EINVAL e restituiscono NULL.

Nella prima chiamata a strtok_s la funzione ignora i delimitatori iniziali e restituisce un puntatore al primo token in str, aggiungendo un carattere Null di terminazione al token. Possono essere suddivisi altri token dal resto di str tramite una serie di chiamate a strtok_s. Ogni chiamata a strtok_s modifica str inserendo un carattere Null dopo il token restituito dalla chiamata. Il puntatore context tiene traccia della stringa letta e della posizione nella stringa in cui deve essere letto il token successivo. Per leggere il token successivo da str, chiamare strtok_s con un valore NULL per l'argomento str e passare lo stesso parametro context. L'argomento NULL str causa strtok_s la ricerca del token successivo nell'oggetto modificato str. L'argomento delimiters può accettare qualsiasi valore da una chiamata alla successiva, quindi il set di delimitatori può variare.

Poiché il context parametro sostituisce i buffer statici usati in strtok e _strtok_l, è possibile analizzare due stringhe contemporaneamente nello stesso thread.

Il valore di output è interessato dall'impostazione dell'impostazione LC_CTYPE della categoria delle impostazioni locali. Per ulteriori informazioni, vedere setlocale.

Le versioni di queste funzioni senza il _l suffisso usano le impostazioni locali del thread corrente per questo comportamento dipendente dalle impostazioni locali. Le versioni con il _l suffisso sono identiche, ma usano invece le impostazioni locali specificate dal locale parametro . Per altre informazioni, vedere Locale.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

Requisiti

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

// 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

Vedi anche

Manipolazione delle stringhe
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
strcspn, wcscspn, _mbscspn_mbscspn_l
strspn, wcsspn, _mbsspn_mbsspn_l