Text.Printf

Авторские права	(c) Lennart Augustsson и Bart Massey 2013
Лицензия	BSD-стиль (см. файл LICENSE в этом дистрибутиве)
Поддержка	Bart Massey <bart@cs.pdx.edu>
Стабильность	временная
Переносимость	переносимая
Safe Haskell	Safe
Язык	Haskell2010

Функции вывода

printf :: PrintfType r => String -> r Исходный код

Форматирует переменное число аргументов с помощью строковой формата в стиле C.

>>> printf "%s, %d, %.4f" "hello" 123 pi
hello, 123, 3.1416

Возвращаемое значение — либо String или (IO a) (которые должны быть (IO ()), но система типов Haskell делает это сложным).

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

В отличие от C printf(3), форматирование этого printf определяется типом аргумента; форматирование специфично для типа. Типы, форматируемые printf «из коробки», это:

• Integral типы, включая Char
• String
• RealFloat типы

printf также расширяем для поддержки других типов: см. ниже.

Спецификация преобразования начинается с символа %, за которым могут следовать ноль или более следующих флагов:

-      left adjust (default is right adjust)
+      always use a sign (+ or -) for signed conversions
space  leading space for positive numbers in signed conversions
0      pad with zeros rather than spaces
#      use an \"alternate form\": see below

Когда оба флага заданы, - переопределяет 0, а + переопределяет пробел. Отрицательный спецификатор ширины в спецификации преобразования * рассматривается как положительный, но подразумевает флаг выравнивания по левому краю.

«Альтернативная форма» для преобразований целых чисел в различных системах счисления аналогична C printf(3):

%o           prefix with a leading 0 if needed
%x           prefix with a leading 0x if nonzero
%X           prefix with a leading 0X if nonzero
%b           prefix with a leading 0b if nonzero
%[eEfFgG]    ensure that the number contains a decimal point

После любого флага необязательно следует ширина поля:

num    field width
*      as num, but taken from argument list

Ширина поля является минимальной, а не максимальной: она будет расширена по мере необходимости, чтобы избежать искажения значения.

Любая ширина поля необязательно следует за точностью:

.num   precision
.      same as .0
.*     as num, but taken from argument list

Отрицательная точность принимается как 0. Значение точности зависит от типа преобразования.

Integral    minimum number of digits to show
RealFloat   number of digits after the decimal point
String      maximum number of characters

Точность для целочисленных типов достигается нулевым заполнением. Если для целочисленного поля заданы и точность, и нулевое заполнение, нулевое заполнение игнорируется.

После любой точности для целочисленных типов необязательно следует модификатор ширины; единственное использование этого модификатора — установить неявный размер операнда для преобразования отрицательного операнда в беззнаковый:

hh     Int8
h      Int16
l      Int32
ll     Int64
L      Int64

Спецификация завершается символом формата:

c      character               Integral
d      decimal                 Integral
o      octal                   Integral
x      hexadecimal             Integral
X      hexadecimal             Integral
b      binary                  Integral
u      unsigned decimal        Integral
f      floating point          RealFloat
F      floating point          RealFloat
g      general format float    RealFloat
G      general format float    RealFloat
e      exponent format float   RealFloat
E      exponent format float   RealFloat
s      string                  String
v      default format          any type

Спецификатор «%v» предоставляется для всех встроенных типов и должен предоставляться для форматировщиков пользовательских типов. Он выбирает «лучшее» представление для данного типа. Для встроенных типов спецификатор «%v» преобразуется следующим образом:

c      Char
u      other unsigned Integral
d      other signed Integral
g      RealFloat
s      String

Несоответствие между типами аргументов и строкой формата, а также любые другие синтаксические или семантические ошибки в строке формата приведут к возникновению исключения во время выполнения.

Обратите внимание, что форматирование типов RealFloat в настоящее время немного отличается от форматирования в C printf(3), следуя вместо этого showEFloat, showFFloat и showGFloat (и их альтернативных версий showFFloatAlt и showGFloatAlt). Это трудно исправить: исправленные версии будут форматировать несовместимым образом. В любом случае поведение Haskell обычно более разумно, чем поведение C. Краткое изложение некоторых ключевых различий:

• Haskell printf никогда не использует стандартную «6-значную» точность, используемую в C printf.
• Haskell printf рассматривает спецификатор «точность» как указание на количество цифр после десятичной точки.
• Haskell printf выводит показатель экспоненты чисел в формате e без избыточного знака плюс и с минимальным возможным количеством цифр.
• Haskell printf будет помещать ноль после десятичной точки, когда это возможно.

hPrintf :: HPrintfType r => Поток -> String -> r Исходный код

Аналогично printf, за исключением того, что вывод осуществляется через указанный Handle. Тип возвращаемого значения ограничен (IO a).

Расширение для новых типов

Это printf можно расширить для форматирования типов, отличных от предоставленных по умолчанию. Это делается путем экземпляризации PrintfArg и предоставления formatArg для типа. Можно предоставить parseFormat для обработки модификаторов, специфичных для типа, но экземпляр по умолчанию обычно является лучшим выбором.

Например:

instance PrintfArg () where
  formatArg x fmt | fmtChar (vFmt 'U' fmt) == 'U' =
    formatString "()" (fmt { fmtChar = 's', fmtPrecision = Nothing })
  formatArg _ fmt = errorBadFormat $ fmtChar fmt

main :: IO ()
main = printf "[%-3.1U]\n" ()

выводит «[() ]». Обратите внимание на использование formatString для удобного управления спецификациями форматирования полей.

class PrintfArg a where Исходный код

Тип класса printf форматируемых значений. Метод formatArg принимает значение и описание формата поля, либо возвращает ошибку из-за плохого описания, либо возвращает ShowS в качестве результата. Экземпляр по умолчанию parseFormat не ожидает модификаторов: это обычный случай. Минимальный экземпляр: formatArg.

type FieldFormatter = FieldFormat -> ShowS Source

Это тип форматировщика полей, реализованный через свой аргумент.

Since: base-4.7.0.0

data FieldFormat Source

Описание форматирования полей для formatArg. См. UNIX printf(3) для описания того, как работает форматирование полей.

Since: base-4.7.0.0

data FormatAdjustment Source

Выравнивание по левому краю или заполнение нулями поля. Они взаимно исключают друг друга, при этом LeftAdjust имеет приоритет.

Since: base-4.7.0.0

data FormatSign Source

Как обрабатывать знак числового поля. Они взаимоисключающие, при этом SignPlus имеет приоритет.

С момента: base-4.7.0.0

vFmt :: Char -> FieldFormat -> FieldFormat Source

Заменяет символ формата 'v' заданным символом формата по умолчанию в FieldFormat. Удобная функция для типов, реализованных пользователем, которые должны поддерживать "%v".

С момента: base-4.7.0.0

Обработка модификаторов, специфичных для типа

В том маловероятном случае, если модификаторы символов какого-либо типа желательны для типа, предоставленного пользователем, можно предоставить ModifierParser, чтобы обработать эти символы. Результирующие модификаторы будут отображаться в FieldFormat для использования специализированным форматировщиком типа.

type ModifierParser = String -> FormatParse Source

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

С момента: base-4.7.0.0

data FormatParse Source

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

С момента: base-4.7.0.0

Стандартные форматировщики

Эти форматировщики для стандартных типов предоставляются для удобства написания новых форматировщиков, специфичных для типа: распространенный паттерн — это передача formatString или formatInteger для выполнения большей части обработки форматирования для нового типа.

formatString :: IsChar a => [a] -> FieldFormatter Source

Форматировщик для значений String.

С момента: base-4.7.0.0

formatChar :: Char -> FieldFormatter Source

Форматировщик для значений Char.

С момента: base-4.7.0.0

formatInt :: (Integral a, Bounded a) => a -> FieldFormatter Source

Форматировщик для значений Int.

С момента: base-4.7.0.0

formatInteger :: Integer -> FieldFormatter Source

Форматировщик для значений Integer.

С момента: base-4.7.0.0

formatRealFloat :: RealFloat a => a -> FieldFormatter Source

Форматировщик для значений RealFloat.

С момента: base-4.7.0.0

Вызов ошибок

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

errorBadFormat :: Char -> a Source

Вызывает perror для указания неизвестного символа формата для данного типа.

С момента: base-4.7.0.0

errorShortFormat :: a Source

Вызывает perror для указания того, что строка формата закончилась преждевременно.

С момента: base-4.7.0.0

errorMissingArgument :: a Source

Вызывает perror для указания отсутствия аргумента в списке аргументов.

С момента: base-4.7.0.0

errorBadArgument :: a Source

Вызывает perror для указания ошибки типа или аналогичной ошибки в данном аргументе.

С момента: base-4.7.0.0

perror :: String -> a Source

Вызывает error с префиксом, специфичным для printf, в строке сообщения.

С момента: base-4.7.0.0

Внутренние детали реализации

Эти типы необходимы для реализации обработки переменного количества аргументов в printf и hPrintf. Их реализация намеренно не видна из этого модуля. Если вы попытаетесь передать аргумент типа, который не является экземпляром соответствующего класса в printf или hPrintf, компилятор сообщит об отсутствии экземпляра PrintfArg. (Все экземпляры PrintfArg являются экземплярами PrintfType.)

class PrintfType t Source

Класс PrintfType предоставляет магию переменных аргументов для printf. Его реализация намеренно не видна из этого модуля. Если вы попытаетесь передать аргумент типа, который не является экземпляром этого класса в printf или hPrintf, компилятор сообщит об отсутствии экземпляра PrintfArg.

class HPrintfType t Исходный код

Класс HPrintfType предоставляет магию переменных аргументов для hPrintf. Его реализация намеренно не видна из этого модуля.

Этот класс необходим как обходное решение совместимости Haskell98 для отсутствия FlexibleInstances.

class IsChar c where Исходный код

Этот класс, имеющий только один пример реализации, используется как обходное решение для того, что String, как конкретный тип, не допускается в качестве примера реализации типа класса. IsChar экспортируется для обеспечения обратной совместимости.