Printf

Материал из Википедии — свободной энциклопедии

printf — функция вывода на stdout (поток стандартного вывода) значений переменных разных типов, отформатированных согласно заданному шаблону.

В общем случае так называют целое семейство функций, различающихся по месту вывода (fprintf записывает строку в файл, sprintf помещает вывод в другую строку), по методу передачи аргументов (vprintf принимает аргументы с помощью va_list), по дополнительным ограничениям (snprintf, vsnprintf имеют дополнительный параметр, ограничивающий максимальный размер строки).

Впервые функция появилась в стандартной библиотеке языка программирования Си, откуда попала в Си++.

Синтаксис строки шаблона вывода (строка форматирования или строка формата) в дальнейшем начал использоваться другими языками программирования (Python ^[1], PHP^[2], Java ^[3]).

Содержание 1 Именование функций 2 Общие соглашения 3 Описание функций 3.1 Имена параметров 3.2 Описание функций 4 Утилита printf 5 Синтаксис строки форматирования 5.1 Структура управляющей последовательности 5.1.1 Флаги 5.1.2 Ширина 5.1.3 Точность 5.2 В рамках стандарта ISO C 5.3 В рамках стандарта POSIX 5.4 Нестандартные расширения 5.4.1 GCC 5.4.2 Microsoft Visual C 6 Ссылки 7 Источники 7.1 Описания функций

[править] Именование функций

Все функции имеют в имени основу printf. Префиксы перед именем функции означают:

• w, перед остальными префиксами (wsnprintf, wvsnprintf) — использующийся фирмой Microsoft префикс для реализаций семейства функций sprintf в операционных системах Windows.
• w, после остальных префиксов (fwprintf, swprintf, wprintf) — функция использует многобайтовую кодировку (wchar_t) вместо обычных строк. (при этом функция swprintf не имеет префикса 'n', хотя и принимает параметр, ограничивающий размер результирующей строки).
• v (vprintf, vsnprintf и т.д.) — фунция вместо переменного числа параметров принимает список аргументов va_list.
• f (fprintf, vfprintf) — вывод результата в файл вместо стандартного вывода.
• s (sprintf, snprintf, vsprintf, vspnprintf) — запись результирующей строки в другую строку.
• n (snprintf, vnsprintf) — наличие параметра, ограничивающего максимальное количество символов для записи результата (используется только вместе с префиксом s).
• a (asprintf, vasprintf) — расширения GNU; функции аналогичные sprintf/vsprintf, но выделяющие достаточный объём памяти с помощью malloc для форматированной строки. Вместо указателя на строку эти функции принимают указатель на указатель на строку, освобождение памяти производит вызвавшая функция.

[править] Общие соглашения

Все функции в качестве одного из параметров (format) принимают строку форматирования (описание синтаксиса строки чуть ниже). Возвращают количество записанных (выведенных) символов, не включая нулевой символ в конце. Количество аргументов, содержащих данные для форматированного вывода, должно быть не менее, чем упомянуто в строке форматирования. «Лишние» аргументы игнорируются.

Функции семейста n (snprintf, vsnprintf) возвращают количество символов, которое было бы выведено, если бы параметр n (ограничивающий количество выводимых символов) был достаточно большим. В случае однобайтовых кодировок, возвращаемое значение соответствует необходимому размеру строки (не включая нулевой символ в конце).

Функции семейства s (sprintf, snprintf, vsprintf, vsnprintf) первым параметром (s) принимают указатель на область памяти, куда будет записана результирующая строка. Функции, не имеющие ограничения по количеству записываемых символов являются опасными функциями, т.к. могут привести к ошибке переполнения буфера, в случае, если выводимая строка окажется больше, чем размер выделенной для вывода области памяти.

Функции семейства f записывают строку в любой открытый файловый поток (параметр stream), в частности, в стандартные потоки вывода (stdout, stderr). fprintf(stdout, format, ...) эквивалентно printf(format, ...).

Функции семейства v принимают аргументы не в виде переменного числа аргументов (как все остальные printf-функции), а в виде списка va_list. При этом при вызове функции макрос va_end не выполняется.

Функции семейства w (первым символом) являются ограниченной реализацией Microsoft семейства функций s: wsprintf, wsnprintf, wvsprintf, wvsnprintf. Эти функции реализованы в динамических библиотеках user32.dll и shlwapi.dll (n функции). Они не поддерживают вывод значений с плавающей запятой, кроме того, wsnprintf и wvsnprintf поддерживают выравнивание текста только по левому краю.

Функции семейства w (wprintf, swprintf) реализуют поддержку многобайтовых кодировок, все функции этого семейства работают с указателями на многобайтные строки (wchar_t).

Функции семейста a (asprintf, avsprintf) выделяют память для строки вывода при помощи функции malloc, освобождение памяти производится в вызвавшей процедуре, в случае ошибки при выполнении функции память не выделяется.

[править] Описание функций

[править] Имена параметров

• format — строка форматирования (формат описан ниже)
• stream — файловый поток для вывода
• s — строка для помещения результата работы функции
• n — переменная, содержащая максимальное допустимое количество символов для строки s
• ap — список значений для вывода
• strp — указатель на указатель на строку для помещения результатов работы функции

[править] Описание функций

• int printf( const char *format, ... );

  Вывод форматированной строки на стандартный вывод

• int fprintf( FILE *stream, const char *format, ... );

  Вывод форматированной строки в поток

• int sprintf( char *s, const char *format, ... );

  Запись форматированной строки в строку без ограничения по размеру строки

• int snprintf( char *s, size_t n, const char *format, ... );

  Запись форматированной строки в строку с ограничением по размеру строки

• int vprintf( const char *format, va_list ap );

  Вывод форматированной строки на стандартный вывод, значения для вывода передаются в функцию в виде списка va_list

• int vfprintf( FILE *stream, const char *format, va_list ap );
  

  Запись форматированной строки в поток, значения для вывода передаются в функцию в виде списка va_list

• int vsprintf( char *s, const char *format, va_list ap );

  Запись форматированной строки в строку без ограничения размера; значения для вывода передаются в функцию в виде списка va_list

• int vsnprintf( char *s, size_t n, const char *format, va_list ap );

  Запись форматированной строки в строку с ограничением на количество выводимых символов. Значения для вывода передаются в функцию в виде списка va_list

• int fwprintf(FILE *stream, const wchar_t *format, ...);

  Запись форматированной строки многобайтовых символов в файл

• int swprintf(wchar_t *ws, size_t n, const wchar_t *format, ...);

  Запись форматированной многобайтовой строки в область памяти (Примечание: не смотря на отсутствие буквы n в названии, эта функция принимает параметр, ограничивающий максимальный размер выходной строки).

• int wprintf(const wchar_t *format, ...);

  Вывод многобайтовой форматированной строки на терминал

• int wsprintf( LPTSTR s, LPCTSTR format, ... );

  Реализация функции sprintf в операционной системе Windows. В отличие от sprintf не поддерживает вывод значений с плавающей запятой, вывод указателей, дополнительно поддерживает обработку многобайтовых строк в однобайтовой версии функции), не поддерживает флаг '+'.

• int wsnprintf( LPTSTR s, int n, LPCTSTR format, ... );

  Реализация функции snprintf в операционной системе Windows. Не поддерживает вывод значений с плавающей запятой и указателей, поддерживает только флаг выравнивания по левому краю.

• int wvsprintf( LPTSTR s, LPCTSTR format, va_list ap );
• int wvsnprintf( LPTSTR s, int n, LPCTSTR format, va_list ap );
• int asprintf(char **strp, const char *format, ...);

  функция записывает результат в строку, память для которой выделяется при помощи malloc

• int vasprintf(char **strp, const char *format, va_list ap);

  функция записывает результат в строку, память для которой выделяется при помощи malloc, значения для вывода передаются в функцию в виде списка va_list

Возвращаемое значение: отрицательное значение - признак ошибки; в случае успеха функции возвращают количество записанных/выведенных байтов (без учёта нулевого байта в конце), функция snprintf выводит количество байт, которые были бы записаны, если бы n было бы достаточного размера.

При вызове snprintf, n может быть равно нулю (в этом случае s может быть нулевым указателем), в этом случае запись не производится, функция только возвращает правильное возвращаемое значение.

В этом месте статьи планируется так же написать о wide-chars functions.

[править] Утилита printf

В рамках стандарта POSIX описана утилита printf, которая выполняет действия, аналогичные функции printf(). Работа утилиты зависит от переменных окружения: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC, NLSPATH.

Утилита имеет следующий формат вызова:

printf format [argument...], где

• format - строка формата, по синтаксису похожая на строку формата функции printf.
• argument - список аргументов (0 или более), записанных в строковой форме.

[править] Синтаксис строки форматирования

Строка форматирования представляет из себя последовательность символов, заканчивающаяся символом с кодом 0. Все символы, кроме управляющих последовательностей, копируются в итоговую строку без изменений. Стандартным признаком начала управляющей последовательности является символ % (знак процента, ASCII код 37), для вывода знака '%' используется его удвоение '%%'.

[править] Структура управляющей последовательности

%[флаги][ширина][.точность][размер]тип
Обязательными полями являются символ начала управляющей последовательности (%) и тип.

[править] Флаги

• - (знак минуса; точнее, дефиса, ASCII код 45) — выводимое значние выравнивается по левому краю в пределах минимальной ширины поля (если флаг не указан — по правому)
• + (знак плюса) — всегда указывать знак (плюс или минус) для выводимого десятичного числового значения (если флаг не указан, то знак выводится только для отрицательных чисел)
• (пробел) — помещать перед результатом пробел, если первый символ значения не знак. + имеет больший приоритет, чем пробел. Используется только для десятичных числовых значений.
• # (октоторп) — «альтернативная форма» вывода значения.
• 0 (символ нуля) — дополнять поле символом 0 до ширины, указанной в поле ширина управляющей последовательности. Символ '-' имеет больший приоритет, чем 0. Используется для типов d, i, o, u, x, X, a, A, e, E, f, F, g, G. Для типов d, i, o, u, x, X, если точность указана, этот флаг игнорируется. Для остальных типов поведение не определено.

[править] Ширина

Ширина (десячитное число) указывает минимальную ширину поля (включая знак для чисел). Если представление величины больше, чем ширина поля, то запись выходит за пределы поля (например, %2i для величины 100 даст значение поля в три символа), если представление величины менее указанного числа, то оно будет дополнено, по-умолчанию, пробелами справа, поведение может меняться предшествующими флагами.

[править] Точность

Точность (десятичное число, записывается через точку)

[править] В рамках стандарта ISO C

[править] В рамках стандарта POSIX

[править] Нестандартные расширения

[править] GCC

[править] Microsoft Visual C

[править] Ссылки

1. ↑ Описание форматирующего оператора для строковых типов в питоне [1]
2. ↑ Описание функции printf в составе PHP [2]
3. ↑ Начиная с версии 1.5, в Java имеется функция java.io.PrintStream.printf() (доступная, в частности, через стандартные переменные System.out и System.err). Она подобна функциональностью классу java.text.MessageFormat, но использует другой, схожий с Си, синтаксис строки формата.

[править] Источники

[править] Описания функций

• printf, fprintf, snprintf, vfprintf, vprintf, vsnprintf, vsprintf в стандарте ISO/IEC 9899:TC2 (ISO C) [3]
• printf, fprintf, sprintf, snprintf в стандарте POSIX [4]
• vprintf, vfprintf, vsprintf, vsnprintf в стандарте POSIX [5]
• wprintf, swprintf, wprintf в стандарте POSIX [6]
• vfwprintf, vswprintf, vwprintf в стандарте POSIX [7]

• wsprintf в MSDN [8]
• wvnsprintf в MSDN [9]
• wnsprintf в MSDN [10]
• wvsprintf в MSDN [11]
• wnsprintf в MSDN [12]
• asprintf, vasprintf в man-pages в Linux [13].