Text.Printf

Авторские права	(с) Леннарт Авгуссон и Барт Масси 2013
Лицензия	BSD-стиль (см. файл LICENSE в этом дистрибутиве)
Поддержка	Барт Масси <bart@cs.pdx.edu>
Стабильность	предварительная
Переносимость	переносимый
Безопасный Haskell	Безопасный
Язык	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 => Handle -> 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 имеет приоритет.

Since: base-4.7.0.0

vFmt :: Char -> FieldFormat -> FieldFormat Source

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

Since: base-4.7.0.0

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

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

type ModifierParser = String -> FormatParse Source

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

Since: base-4.7.0.0

data FormatParse Source

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

Since: base-4.7.0.0

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

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

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

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

Since: base-4.7.0.0

formatChar :: Char -> FieldFormatter Source

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

Since: base-4.7.0.0

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

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

Since: base-4.7.0.0

formatInteger :: Integer -> FieldFormatter Source

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

Since: base-4.7.0.0

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

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

Since: base-4.7.0.0

Вызов ошибок

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

errorBadFormat :: Char -> a Source

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

Since: base-4.7.0.0

errorShortFormat :: a Source

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

Since: base-4.7.0.0

errorMissingArgument :: a Source

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

Since: base-4.7.0.0

errorBadArgument :: a Source

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

Since: base-4.7.0.0

perror :: String -> a Source

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

Since: base-4.7.0.0

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

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

class PrintfType t Source

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

class HPrintfType t Source

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

Этот класс необходим как обходной путь совместимости с Haskell98 из-за отсутствия FlexibleInstances.

class IsChar c where Source

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