| format
|
—
|
Указатель на завершающуюся нулем строку, определяющую характер, как читать ввод.
Строка format состоит из
- непробельных многобайтовых символов, за исключением
%: каждый такой символ в строке формата потребляет ровно один идентичный символ из входного потока, или приводит к сбою функции, если следующий символ в потоке не соответствует формату.
- пробельные символы: любой одиночный пробельный символ в строке формата поглощает все доступные последовательные пробельные символы из ввода (определяется так же, как если бы вы вызывали isspace в цикле). Обратите внимание, что нет никакой разницы между
"\n", " ", "\t\t" или другими пробельными символами в строке формата.
- спецификации преобразования. Каждая спецификация преобразования имеет следующий формат:
- (необязательно) символ подавления присваивания
*. Если эта опция присутствует, функция не присваивает результат преобразования ни одному принимающему аргументу.
- (необязательно) целое число (больше нуля), определяющее максимальную ширину поля, то есть максимальное количество символов, которое функция может использовать при выполнении преобразования, указанного текущей спецификацией преобразования. Обратите внимание, что
%s и %[ могут привести к переполнению буфера, если ширина не указана.
- (необязательно) модификатор длины, указывающий размер принимающего аргумента, то есть фактический тип назначения. Это влияет на точность преобразования и правила переполнения. Тип назначения по умолчанию различен для каждого типа преобразования (смотрите таблицу ниже).
- спецификатор формата преобразования.
Доступны следующие спецификаторы формата:
Спецификатор
преобразования
|
Объяснение
|
Тип аргумента
|
Модификатор длины →
|
hh
(C++11)
|
h
|
(нет)
|
l
|
ll
(C++11)
|
j
(C++11)
|
z
(C++11)
|
t
(C++11)
|
L
|
%
|
Соответствует литералу %.
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
c
|
- Соответствует символу или последовательности символов.
Если используется спецификатор ширины, он точно соответствует ширине символов (аргумент должен быть указателем на массив с достаточным пространством). В отличие от %s и %[, не добавляет в массив нулевой символ.
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
s
|
- Соответствует последовательности символов без пробельных символов (строка).
Если используется спецификатор ширины, соответствует до ширина или до первого пробельного символа, в зависимости от того, что появляется первым. Всегда сохраняет нулевой символ в дополнение к совпадающим символам (поэтому в массиве аргументов должно быть место как минимум для ширина+1 символов)
|
[набор]
|
- Соответствует непустой последовательности символов из набора символов.
Если первый символ набора ^, то совпадают все символы, не входящие в набор. Если набор начинается с ] или ^], то символ ] также включается в набор. Реализация определяет, может ли символ - в неначальной позиции в наборе сканирования указывать диапазон, как в [0-9]. Если используется спецификатор ширины, соответствует только ширине. Всегда сохраняет нулевой символ в дополнение к совпадающим символам (поэтому в массиве аргументов должно быть место как минимум для ширина+1 символов)
|
d
|
- Соответствует десятичному целому числу.
Формат числа такой же, как ожидает strtol со значением 10 для аргумента base
|
signed char* или unsigned char*
|
signed short* или unsigned short*
|
signed int* или unsigned int*
|
signed long* или unsigned long*
|
signed long long* или unsigned long long*
|
|
|
|
Н/Д
|
i
|
- Соответствует целому числу.
Формат числа такой же, как ожидает strtol со значением 0 для аргумента base (база определяется по первым проанализированным символам)
|
u
|
- Соответствует беззнаковому десятичному целому числу.
Формат числа такой же, как ожидает strtoul со значением 10 для аргумента base.
|
o
|
- Соответствует беззнаковому восьмеричному целому.
Формат числа такой же, как ожидает strtoul со значением 8 для аргумента base
|
x, X
|
- Соответствует беззнаковому шестнадцатеричному целому.
Формат числа такой же, как ожидает strtoul со значением 16 для аргумента base
|
n
|
- Возвращает количество прочитанных на данный момент символов.
Никакие входные данные не потребляются. Не увеличивает счётчик присваиваний. Если в спецификаторе определён оператор подавления присваивания, поведение не определено.
|
a, A(C++11)
e, E
f, F
g, G
|
- Соответствует числу с плавающей запятой.
Формат числа такой же, как ожидает strtof
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
|
p
|
- Соответствует определённой реализацией последовательности символов, определяющей указатель.
Семейство функций printf должно создавать одну и ту же последовательность, используя спецификатор формата %p
|
Н/Д
|
Н/Д
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Для каждого спецификатора преобразования, кроме n, самая длинная последовательность входных символов, которая не превышает указанную ширину поля и которая либо в точности соответствует ожиданиям спецификатора преобразования, либо является префиксом ожидаемой последовательности, потребляется из потока. Первый символ, если он есть, после этой использованной последовательности остаётся непрочитанным. Если потребляемая последовательность имеет нулевую длину или если потребляемая последовательность не может быть преобразована, как указано выше, происходит ошибка сопоставления, за исключением случаев, когда достигнут конец файла, ошибка кодирования или ошибка чтения препятствуют вводу из потока, и в этом случае это сбой ввода.
Все спецификаторы преобразования, кроме [, c и n, используют и отбрасывают все ведущие пробельные символы (определяемые как если бы путём вызова isspace) перед попыткой анализа ввода. Эти использованные символы не учитываются при расчёте указанной максимальной ширины поля.
Спецификаторы преобразования lc, ls и l[ выполняют преобразование многобайтовых символов в широкие, как если бы вызывали mbrtowc с объектом mbstate_t, инициализированным нулём перед преобразованием первого символа.
Спецификаторы преобразования s и [ всегда сохраняют нулевой терминатор в дополнение к совпавшим символам. Размер целевого массива должен быть как минимум на единицу больше указанной ширины поля. Использование %s или %[ без указания размера целевого массива так же небезопасно, как и std::gets.
Правильные спецификации преобразования для целочисленных типов фиксированной ширины (int8_t и т.д.) определены в заголовке <cinttypes> (хотя SCNdMAX, SCNuMAX и т.д. являются синонимами %jd, %ju и т.д.).
После действия каждого спецификатора преобразования существует точка последовательности; это позволяет хранить несколько полей в одной и той же переменной-приёмнике.
При анализе неполного значения с плавающей запятой, которое заканчивается экспонентой без цифр, например при анализе "100er" с спецификатором преобразования %f, последовательность "100e" (самый длинный префикс возможно допустимого числа с плавающей запятой) потребляется, что приводит к ошибке сопоставления (используемая последовательность не может быть преобразована в число с плавающей запятой), при этом остаётся "r". Некоторые существующие реализации не следуют этому правилу и откатываются, чтобы использовать только "100", оставляя "er", например glibc bug 1765.
Оригинал: pointer to a null-terminated character string specifying how to read the input.
Строка format состоит из
- непробельных многобайтовых символов, за исключением
%: каждый такой символ в строке формата потребляет ровно один идентичный символ из входного потока, или приводит к сбою функции, если следующий символ в потоке не соответствует формату.
- пробельные символы: любой одиночный пробельный символ в строке формата поглощает все доступные последовательные пробельные символы из ввода (определяется так же, как если бы вы вызывали isspace в цикле). Обратите внимание, что нет никакой разницы между
"\n", " ", "\t\t" или другими пробельными символами в строке формата.
- спецификации преобразования. Каждая спецификация преобразования имеет следующий формат:
- (необязательно) символ подавления присваивания
*. Если эта опция присутствует, функция не присваивает результат преобразования ни одному принимающему аргументу.
- (необязательно) целое число (больше нуля), определяющее максимальную ширину поля, то есть максимальное количество символов, которое функция может использовать при выполнении преобразования, указанного текущей спецификацией преобразования. Обратите внимание, что
%s и %[ могут привести к переполнению буфера, если ширина не указана.
- (необязательно) модификатор длины, указывающий размер принимающего аргумента, то есть фактический тип назначения. Это влияет на точность преобразования и правила переполнения. Тип назначения по умолчанию различен для каждого типа преобразования (смотрите таблицу ниже).
- спецификатор формата преобразования.
Доступны следующие спецификаторы формата:
Спецификатор
преобразования
|
Объяснение
|
Тип аргумента
|
Модификатор длины →
|
hh
(C++11)
|
h
|
(нет)
|
l
|
ll
(C++11)
|
j
(C++11)
|
z
(C++11)
|
t
(C++11)
|
L
|
%
|
Соответствует литералу %.
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
c
|
- Соответствует символу или последовательности символов.
Если используется спецификатор ширины, он точно соответствует ширине символов (аргумент должен быть указателем на массив с достаточным пространством). В отличие от %s и %[, не добавляет в массив нулевой символ.
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
s
|
- Соответствует последовательности символов без пробельных символов (строка).
Если используется спецификатор ширины, соответствует до ширина или до первого пробельного символа, в зависимости от того, что появляется первым. Всегда сохраняет нулевой символ в дополнение к совпадающим символам (поэтому в массиве аргументов должно быть место как минимум для ширина+1 символов)
|
[набор]
|
- Соответствует непустой последовательности символов из набора символов.
Если первый символ набора ^, то совпадают все символы, не входящие в набор. Если набор начинается с ] или ^], то символ ] также включается в набор. Реализация определяет, может ли символ - в неначальной позиции в наборе сканирования указывать диапазон, как в [0-9]. Если используется спецификатор ширины, соответствует только ширине. Всегда сохраняет нулевой символ в дополнение к совпадающим символам (поэтому в массиве аргументов должно быть место как минимум для ширина+1 символов)
|
d
|
- Соответствует десятичному целому числу.
Формат числа такой же, как ожидает strtol со значением 10 для аргумента base
|
signed char* или unsigned char*
|
signed short* или unsigned short*
|
signed int* или unsigned int*
|
signed long* или unsigned long*
|
signed long long* или unsigned long long*
|
|
|
|
Н/Д
|
i
|
- Соответствует целому числу.
Формат числа такой же, как ожидает strtol со значением 0 для аргумента base (база определяется по первым проанализированным символам)
|
u
|
- Соответствует беззнаковому десятичному целому числу.
Формат числа такой же, как ожидает strtoul со значением 10 для аргумента base.
|
o
|
- Соответствует беззнаковому восьмеричному целому.
Формат числа такой же, как ожидает strtoul со значением 8 для аргумента base
|
x, X
|
- Соответствует беззнаковому шестнадцатеричному целому.
Формат числа такой же, как ожидает strtoul со значением 16 для аргумента base
|
n
|
- Возвращает количество прочитанных на данный момент символов.
Никакие входные данные не потребляются. Не увеличивает счётчик присваиваний. Если в спецификаторе определён оператор подавления присваивания, поведение не определено.
|
a, A(C++11)
e, E
f, F
g, G
|
- Соответствует числу с плавающей запятой.
Формат числа такой же, как ожидает strtof
|
Н/Д
|
Н/Д
|
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
|
p
|
- Соответствует определённой реализацией последовательности символов, определяющей указатель.
Семейство функций printf должно создавать одну и ту же последовательность, используя спецификатор формата %p
|
Н/Д
|
Н/Д
|
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Н/Д
|
Для каждого спецификатора преобразования, кроме n, самая длинная последовательность входных символов, которая не превышает указанную ширину поля и которая либо в точности соответствует ожиданиям спецификатора преобразования, либо является префиксом ожидаемой последовательности, потребляется из потока. Первый символ, если он есть, после этой использованной последовательности остаётся непрочитанным. Если потребляемая последовательность имеет нулевую длину или если потребляемая последовательность не может быть преобразована, как указано выше, происходит ошибка сопоставления, за исключением случаев, когда достигнут конец файла, ошибка кодирования или ошибка чтения препятствуют вводу из потока, и в этом случае это сбой ввода.
Все спецификаторы преобразования, кроме [, c и n, используют и отбрасывают все ведущие пробельные символы (определяемые как если бы путём вызова isspace) перед попыткой анализа ввода. Эти использованные символы не учитываются при расчёте указанной максимальной ширины поля.
Спецификаторы преобразования lc, ls и l[ выполняют преобразование многобайтовых символов в широкие, как если бы вызывали mbrtowc с объектом mbstate_t, инициализированным нулём перед преобразованием первого символа.
Спецификаторы преобразования s и [ всегда сохраняют нулевой терминатор в дополнение к совпавшим символам. Размер целевого массива должен быть как минимум на единицу больше указанной ширины поля. Использование %s или %[ без указания размера целевого массива так же небезопасно, как и std::gets.
Правильные спецификации преобразования для целочисленных типов фиксированной ширины (int8_t и т.д.) определены в заголовке <cinttypes> (хотя SCNdMAX, SCNuMAX и т.д. являются синонимами %jd, %ju и т.д.).
После действия каждого спецификатора преобразования существует точка последовательности; это позволяет хранить несколько полей в одной и той же переменной-приёмнике.
При анализе неполного значения с плавающей запятой, которое заканчивается экспонентой без цифр, например при анализе "100er" с спецификатором преобразования %f, последовательность "100e" (самый длинный префикс возможно допустимого числа с плавающей запятой) потребляется, что приводит к ошибке сопоставления (используемая последовательность не может быть преобразована в число с плавающей запятой), при этом остаётся "r". Некоторые существующие реализации не следуют этому правилу и откатываются, чтобы использовать только "100", оставляя "er", например glibc bug 1765.
Текст был переведён автоматически используя Переводчик Google. Вы можете проверить и исправить перевод. Для инструкций щёлкните сюда. |
