strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

Artykuł
06/09/2015

Znajduje następny token w ciągu, używając bieżących ustawień regionalnych lub przekazanych ustawień regionalnych.Te wersje strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

Ważne
_mbstok_s i _mbstok_s_l nie można używać w aplikacjach korzystających ze środowiska wykonawczego systemu Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /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 
);

Parametry

strToken
Ciąg zawierający token lub tokeny.
strDelimit
Zestaw znaków ogranicznika.
context
Używany do przechowywania informacji o pozycji między wywołaniami strtok_s
locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zwraca wskaźnik do następnego tokenu znalezionego w strToken.Zwracają NULL, gdy nie znaleziono więcej tokenów.Każde wywołanie modyfikuje strToken przez podstawienie znaku NULL dla pierwszego ogranicznika występującego po zwróconym tokenie.

Warunki błędów

strToken	strDelimit	context	Wartość zwrócona	errno
NULL	jakakolwiek	wskaźnik do pustego wskaźnika	NULL	EINVAL
jakakolwiek	NULL	jakakolwiek	NULL	EINVAL
jakakolwiek	jakakolwiek	NULL	NULL	EINVAL

Jeśli strToken jest NULL, ale kontekst jest wskaźnikiem do prawidłowego wskaźnika kontekstu, błąd nie wystąpi.

Uwagi

Funkcja strtok_s znajduje następny token w strToken.Zestaw znaków w strDelimit określa możliwe ograniczniki tokenu do znalezienia w strToken w bieżącym wywołaniu.wcstok_s i _mbstok_sto wersja znaków dwubajtowych i wielobajtowych dla strtok_s.Argumenty i wartości zwracane przez wcstok_s i _wcstok_s_l są ciągami znaków dwubajtowych; zwracane przez _mbstok_s i _mbstok_s_l są ciągami znaków wielobajtowych.Te trzy funkcje w innych wypadkach zachowują się identycznie.

Ta funkcja sprawdza poprawność swoich parametrów.Jeśli wystąpi warunek błędu, jak w tabeli Warunki błędów, zostanie wywołany procedura obsługi nieprawidłowego parametru, jak opisano w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje ustawiają errno jako EINVAL i zwracają NULL.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

Przy pierwszym wywołaniu strtok_s, funkcja pomija wiodące ograniczniki i zwraca wskaźnik do pierwszego tokenu w strToken, kończąc token znakiem null.Więcej tokenów można podzielić z pozostałej części strToken przez szereg wywołań strtok_s.Każde wywołanie strtok_s modyfikuje strToken wstawiając znak null po tokenie zwróconym przez to wywołanie.Wskaźnik context przechowuje informacje o tym, który ciąg jest odczytywany i gdzie w ciągu znajduje się następny token do odczytania.Aby odczytać następny token z wywołania strToken, należy wywołać strtok_s z wartością NULL dla argumentu strToken i przekazać ten sam parametr context.Argument strToken o wartości NULL powoduje, że strtok_s szuka następnego tokenu w zmodyfikowanym strToken.Argument strDelimit może przyjąć dowolną wartość z jednego wywołania do drugiego, więc zestaw ograniczników może się różnić.

Ponieważ parametr context zastępuje bufory statyczne używane w strtok i _strtok_l, istnieje możliwość, aby przeanalizować dwa ciągi równocześnie w jednym wątku.

Wartość wyjściowa jest zależna od konfiguracji ustawień kategorii LC_CTYPE ustawień regionalnych; zobacz setlocale, aby uzyskać więcej informacji.Wersje tych funkcji, które nie mają przyrostka _l używają bieżących ustawień regionalnych dla wszelkich zachowań zależnych od ustawień lokalnych; wersje, które mają przyrostek _l są identyczne, z tą różnicą, że w zamian korzystają z przekazanego parametru ustawień regionalnych.Aby uzyskać więcej informacji, zobacz Regionalne.

Wymagania

Procedura	Wymagany nagłówek
strtok_s	<Ciąg>
_strtok_s_l	<Ciąg>
wcstok_s, _wcstok_s_l	<ciągo.h> lub <wchar.h>
_mbstok_s, _mbstok_s_l	<mbCiąg.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność.

Przykład

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