sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Artykuł
06/09/2015

Odczyty sformatowanych danych z ciągu.Te wersje sscanf, _sscanf_l, swscanf, _swscanf_l mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument ] ...
);

Parametry

buffer
Przechowywane dane
format
Ciąg formantu formatu.Aby uzyskać więcej informacji, zobacz Pola specyfikacji formatu dla funkcji wscanf.
argument
Argumenty opcjonalne
locale
Ustawienia regionalne, które mają zostać użyte.

Wartość zwracana

Każda z tych funkcji zwraca liczbę pól pomyślnie przekonwertowanych i przypisanych; zwracana wartość nie uwzględnia pól, które zostały odczytane, ale nie przypisane.Zwracana wartość wynosząca 0 wskazuje, że nie przydzielono żadnych pól.Wartością zwracaną jest EOF dla błędu lub w przypadku osiągnięcia końca ciągu przed dokonaniem pierwszej konwersji.

Jeśli buffer lub format jest wskaźnikiem NULL, wywoływany jest nieprawidłowy parametr uchwytu, zgodnie z opisem Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje zwracają wartość -1 i ustawiają errno na EINVAL

Aby uzyskać informacje o tych i innych kodach błędów, zobacz errno, _doserrno, _sys_errlist, and _sys_nerr.

Uwagi

Funkcja sscanf_s odczytuje dane z buffer do lokalizacji podanej przez każdy argument.Argumenty po ciągu formatu określają wskaźniki do zmiennych, które mają typ odpowiadający specyfikatorowi typu w parametrze format.W przeciwieństwie do mniej bezpiecznej wersji sscanf, parametr rozmiaru buforu jest wymagany podczas używania znaków pól typu c, C, s, S lub zestawów kontroli ciągów, które są ujęte w [].Rozmiar buforu w znakach musi zostać dostarczony jako dodatkowy parametr natychmiast po każdym parametrze buforu, który go wymaga.Na przykład, podczas czytania ciągu znaków, rozmiar buforu dla tego ciągu jest przekazywany w następujący sposób:

wchar_t ws[10];

swscanf_s(in_str, L"%9s", ws, _countof(ws)); // buffer size is 10, width specification is 9

Rozmiar buforu obejmuje kończącą wartość null.Pole określania szerokości można wykorzystać do zapewnienia, że token, który jest wczytywany zmieści się w buforze.Jeśli nie jest używane pole specyfikacji szerokości, a odczyt tokenu jest zbyt duży, aby zmieścić się w buforze, nic nie jest zapisywane do tego buforu.

W przypadku znaków pojedynczy znak może wyglądać następująco:

wchar_t wc;

swscanf_s(in_str, L"%c", &wc, 1);

W tym przykładzie pokazano jak się odczytuje pojedynczy znak z ciągu wejściowego i przechowuje go w buforze znaków dwubajtowych.Po przeczytaniu wielu znaków dla ciągów niezakończonych znakiem null, liczby całkowite bez znaku są używane jako specyfikacja szerokości i rozmiaru buforu.

char c[4];

sscanf_s(input, "%4c", &c, _countof(c)); // not null terminated

Aby uzyskać więcej informacji, zobacz scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l i scanf — Znaki pola typu.

[!UWAGA]

Parametr rozmiaru ma typ unsigned, nie size_t.

Argument format kontroluje interpretację pól wejściowych i ma taką samą formę i zadanie, co argument format dla funkcji scanf_s.Jeśli kopiowanie odbywa się między nakładającymi się ciągami, zachowanie jest niezdefiniowane.

swscanf_s to wersja znaku dwubajtowego sscanf_s;; argumenty dla swscanf_s to ciągi znaku dwubajtowego.sscanf_s nie obsługuje wielobajtowych znaków szesnastkowych.swscanf_s nie obsługuje znaków "strefa zgodności" ani szesnastkowych znaków pełnej szerokości Unicode.W innych przypadkach swscanf_s i sscanf_s zachowują się identycznie.

Funkcje w wersji z przyrostkiem _l są identyczne, z tą różnicą, że używają parametru ustawień regionalnych, który jest przekazywany zamiast ustawień regionalnych bieżącego wątku.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

Wymagania

Procedura	Wymagany nagłówek
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> lub <wchar.h>

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

Przykład

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus NULL terminator
   sscanf_s( tokenstring, "%s", s, _countof(s) );
   sscanf_s( tokenstring, "%c", &c, sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}