sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Статья
06/09/2015

Чтение форматированных данных из строки. В этих версиях sscanf, _sscanf_l, swscanf, _swscanf_l усовершенствована безопасность, как описано в разделе Функции безопасности в 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 ] ...
);

Параметры

buffer
Сохраненные данные
format
Строка управления форматом. Для получения дополнительной информации см. Поля спецификации формата. Функции scanf и wscanf.
argument
Необязательные аргументы
locale
Используемый языковой стандарт

Возвращаемое значение

Каждая из этих функций возвращает количество полей, которые успешно преобразуются и назначаются; возвращаемое значение не включает поля, которые были считаны, но не присваиваются. Возвращаемое значение 0 указывает, что поля не были присвоены. Возвращаемое значение равно EOF в случае ошибки или если конец строки достигнут до первого преобразования.

Если параметр buffer или format указывает на NULL, вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эти функции возвращают -1 и устанавливают для errno значение EINVAL.

Сведения об этих и других кодах ошибок см. в разделе errno, _doserrno, _sys_errlist, and _sys_nerr.

Заметки

Функция sscanf_s считывает данные из buffer в расположение, которое задается каждым argument. Аргументы после строки формата задают указатели на переменные, имеющие тип, который соответствует спецификатору типа в format. В отличие от менее безопасной версии sscanf, параметр размера буфера является обязательным при использовании символов поля типа c, C, s, S или строковых управляющих наборов, заключенных в []. Размер буфера в символах следует указывать в качестве дополнительного параметра сразу после каждого параметра буфера, для которого он требуется. Например, при чтении в строку, размер буфера для этой строки передается следующим образом:

wchar_t ws[10];

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

Размер буфера включает конечное значение NULL. Поле спецификации ширины может использоваться, чтобы гарантировать, что считываемый токен поместится в буфер. Если не используется поле спецификации ширины, и токен считанный слишком велик чтобы влезть в буфер, ничего не записывается в этот буфер.

В случае символов, отдельный символ может быть прочитан следующим образом:

wchar_t wc;

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

В данном примере демонстрируется чтение символа из входной строки, а затем его сохранение в буфере расширенных символов. При чтении нескольких символов для строк, незавершенных null, беззнаковые целые числа используются как спецификация ширины и размер буфера.

char c[4];

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

Дополнительные сведения см. в разделах scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l и Символы поля типа scanf.

Примечание

Параметр размера — типа unsigned, а не size_t.

Аргумент format управляет интерпретацией полей ввода и имеет те же форму и функциональные возможности, что и аргумент format для функции scanf_s. Если копирование производится между перекрывающимися строками, поведение не определено.

swscanf_s — версия sscanf_s; для расширенных символов; аргументы для swscanf_s представляют собой строки расширенных символов. sscanf_s не обрабатывает многобайтовые шестнадцатеричные символы. swscanf_s не обрабатывает полноширинные шестнадцатеричные символы юникода или символы "зоны совместимости". В противном случае поведение swscanf_s и sscanf_s идентично.

Версии этих функций, имеющие суффикс _l, идентичны за исключением того, что они используют переданный параметр языкового стандарта вместо языкового стандарта текущего потока.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

Требования

Подпрограмма	Обязательный заголовок
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> или <wchar.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

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