Форматирование произвольных объектов

Это приложение объясняет, как можно форматировать произвольные объекты в строки. Описание разделено на две части. В первой части, Сводке, описываются основные концепции форматирования. Этот раздел предназнaчен для пользователей, которые хотят начать быстро и уже знакомы с языками форматирования печати и программирования (printf() на C или класса Java Formatter). Во второй части, Детали, представлены специфичные подробности реализации. Она предназначена для тех, кто хочет ознакомиться с более подробной спецификацией по форматированию поведения.

Сводка

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

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

Каждый метод, который производит отформатированный вывод, требует строки формата и списка параметров. Строка формата является String который может содержать фиксированный текст и один или более встроенные спецификаторы формата. Рассмотрите следующий пример:  

format("Duke's Birthday: %1$tm %1$te,%1$tY", d);

Эта строка формата является первым параметром format метод. Это содержит три спецификатора формата %1$tm, %1$te и %1$tY, которые указывают, как параметры должны быть обработаны и где они должны быть вставлены в текст. Остающиеся части строки формата являются фиксированным текстом включая "Dukes Birthday: " и любые другие пробелы или пунктуация. Список параметров состоит из всех параметров, которые передают к методу после строки формата. В вышеупомянутом примере список параметров имеет размер один и состоит из Дата d.

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

%[argument_index$][flags][width][.precision]conversion

Дополнительный argument_index является десятичным целым числом, указывающим на позицию параметра в списке параметров. На первый параметр ссылаются 1$, второе 2$ и т.д.

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

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

Дополнительная точность является неотрицательным десятичным целым числом, обычно используемым, чтобы ограничить число символов. Определённое поведение зависит от преобразования.

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

  • Спецификаторы формата для типов, которые представляют даты и времена, имеют следующий синтаксис:

%[argument_index$][flags][width]conversion

Дополнительные argument_index, флаги и ширина определяются, как выше.

Необходимое преобразование является двумя символьными последовательностями. Первый символ t или T. Второй символ указывает на формат, который будет использоваться.

  • У спецификаторов формата, которые не соответствуют параметрам, есть следующий синтаксис:

%[flags][width]conversion

       Дополнительные флаги и ширина определяются, как выше.

Необходимое преобразование является контентом указания символа, который будет вставлен в вывод.

Преобразования

Преобразования делятся на следующие категории:

1. Общий - может быть применён к любому типу параметра

2. Символ - может быть применён к основным типам, которые представляют символы Unicode

3. Числовой

  1. Интеграл - может быть применён к целочисленным типам Java: Целое или Длинное

  2. Плавающая точка - может быть применена к Java типы с плавающей точкой: Плавающая точка или Двойное

4. Дата/Время - может быть применена к типу Дата

5. Процент - производит литерал '%' ('\u0025')

6. Разделитель строки - производит специфичный для платформы разделитель строки

Следующая таблица суммирует поддерживаемые преобразования. Преобразования, обозначенные символом верхнего регистра (то есть. 'B', 'H', 'S', 'C', 'X', 'E', 'G', 'A', и 'T') то же самое как те для соответствующих строчных символов преобразования за исключением того, что результат преобразовывается в верхний регистр согласно правилам преобладания Locale.

Преобразование

Категория параметра

Описание

'b', 'B'

общий

Если аргумент параметра null, тогда результат false. Если аргумент является a boolean или Boolean, тогда результатом является строка. Иначе результатом является true.

'h', 'H'

общий

Если аргумент параметра null, тогда результат "null". Иначе результат получается путём конвертирования числа в шестнадцатеричную строку.

's', 'S'

общий

Если аргумент параметра null, тогда результат "null". Иначе аргумент конвертируется в строку.

'c', 'C'

символ

Результатом является символ Unicode

'd'

интеграл

Результат форматируется как десятичное целое число

'o'

интеграл

Результат форматируется как восьмеричное целое число

'x', 'X'

интеграл

Результат форматируется как шестнадцатеричное целое число

'e', 'E'

плавающая точка

Результат форматируется как десятичное число в компьютеризированном экспоненциальном представлении

'f'

плавающая точка

Результат форматируется как десятичное число

'g', 'G'

плавающая точка

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

'a', 'A'

плавающая точка

Результат форматируется как шестнадцатеричное число с плавающей точкой с мантиссой и экспонентой  

't', 'T'

дата/время

Префикс для символов преобразования даты и времени.

'%'

процент

Результатом является литерал '%' ('\u0025') 25')

'n'

строковый разделитель

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

Любые символы, не явно определённые как преобразования, недопустимы и резервируются для будущих расширений.

Преобразования даты/времени

Следующая дата и символы суффикса преобразования времени определяются для 't' и 'T' преобразования.

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

'H'

Час дня для 24-часовых часов, отформатированных как две цифры с начальным нулём по мере необходимости, то есть 00 - 23.

'I'

Час для 12-часовых часов, отформатированных как две цифры с начальным нулём по мере необходимости, то есть 01 - 12.

'k'

Час дня для 24-часовых часов, то есть 0 - 23.

'l'

Час для 12-часовых часов, то есть 1 - 12.

'M'

Минута в течение часа, отформатированного как две цифры с начальным нулём по мере необходимости, то есть 00 - 59.

'S'

Секунды в течение минуты, отформатированные как две цифры с начальным нулём по мере необходимости, то есть 00 - 60 ("60" - специальное значение, требуемое поддерживать секунды прыжка).

'L'

Миллисекунда в пределах второго, отформатированного как три цифры с начальными нулями по мере необходимости, то есть 000 - 999.

'N'

Наносекунда в пределах второго, отформатированного как девять цифр с начальными нулями по мере необходимости, то есть 000000000 - 999999999.

'p'

Специфичный для региональных настроек маркер утра или дня в нижнем регистре, например,"am" или "pm". Использование префикса преобразования 'T' силы этот вывод к верхнему регистру.

'z'

Стиль RFC 822 числовое смещение часового пояса от GMT, например. -0800.

'Z'

Строка, представляющая сокращение для часового пояса. Региональные настройки средства форматирования заменят региональные настройки параметра (если есть).

's'

Секунды с начала эпохи, начавшейся 1 января 1970 00:00:00 UTC, то есть минимальное подписанное 64-битовое целое значение, разделённое на 1000 до максимального подписанного 64-битового целого, разделённого на 1000.

'Q'

Миллисекунды с начала эпохи, запускающейся 1 января 1970 00:00:00 UTC, то есть минимальное подписанное 64-битовое целое значение, разделённое на 1000 до максимального подписанного 64-битового целого, разделённого на 1000.

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

'B'

Специфичное для региональных настроек полное имя месяца, например, "январь", "февраль".

'b'

Специфичное для региональных настроек сокращённое имя месяца, например, "янв", "фев".

'h'

То же самое, как 'b'.

'A'

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

'a'

Специфичное для региональных настроек краткое название дня недели, например, "вск", "пон"

'C'

Год из четырёх знаков, разделённый на 100, отформатированный как две цифры с начальным нулём по мере необходимости, то есть 00 - 99

'Y'

Год, отформатированный как по крайней мере четыре цифры с начальными нулями по мере необходимости, например. 0092 равняется 92 CE для Григорианского календаря.

'y'

Последние две цифры года, отформатированного с начальными нулями по мере необходимости, то есть 00 - 99.

'j'

День года, отформатированного как три цифры с начальными нулями по мере необходимости, например, 001 - 366 для Григорианского календаря.

'm'

Месяц, отформатированный как две цифры с начальными нулями по мере необходимости, то есть 01 - 13.

'd'

День месяца, отформатированного как две цифры с начальными нулями по мере необходимости, то есть 01 - 31

'e'

День месяца, отформатированного как две цифры, то есть 1 - 31.

Следующие символы преобразования используются для того, чтобы отформатировать общие составы даты/времени.

'R'

Время, отформатированное для 24-часовых часов как "%tH:%tM"  

'T'

Время, отформатированное для 24-часовых часов как "%tH:%tM:%tS".

'r'

Время, отформатированное для 12-часовых часов как "%tI:%tM:%tS %Tp". Расположение маркера утра или дня ('%Tp') может быть зависимым от региональных настроек.

'D'

Дата, отформатированная как "%tm/%td/%ty".

'F'

ISO 8601 полная дата, отформатированная как "%tY-%tm-%td".

'c'

Дата и время, отформатированное как "%ta %tb %td %tT %tZ %tY", например. "Sun Jul 20 16:17:00 EDT 1969".

Любые символы, не явно определённые как суффиксы преобразования даты/времени, недопустимы и резервируются для будущих расширений.

Флаги

Следующая таблица суммирует поддерживаемые флаги. y означает, что флаг поддерживается для обозначенных типов параметра.

Флаг

Общий

Символ

Интеграл

Плавающая точка

Дата/Время

Описание

'-'

y

y

y

y

y

Результат будет выровнен слева по ширине.

'#'

y1

-

y3

y

-

Результат должен использовать зависимую от преобразования альтернативную форму

'+'

-

-

y4

y

-

Результат будет всегда включать знак

' '

-

-

y4

y

-

Результат будет включать ведущее пространство для положительных значений

'0'

-

-

y

y

-

Результат будет дополнен нулем  

','

-

-

y2

y5

-

Результат будет включать специфичные для региональных настроек разделители группировки

'('

-

-

y4

y5

-

Результат заключит отрицательные числа в круглые скобки

1 Зависит от определения.

2 Только для 'd' преобразования.

3 Только для преобразований 'o', 'x' и 'X'.

4 Для 'd', применимого к Целому и Длинному.

5 Только для преобразований 'e', 'E', 'f', 'g', and 'G'.

Любые символы, не явно определённые как флаги, недопустимы и резервируются для будущих расширений.

Ширина  

Ширина является минимальным числом символов, которые будут записаны в вывод. Для преобразования разделителя строки ширина не применима; если это обеспечено, то будет выдано исключение.

Точность

Для общих типов параметра точность является максимальным количеством символов, которые будут записаны в вывод.

Для преобразований с плавающей точкой 'e', 'E', и 'f' точность является числом цифр после десятичного разделителя. Если преобразование 'g' или 'G', тогда точность является общим количеством цифр в получающейся величине после округления. Если преобразование 'a' или 'A', тогда точность не должна быть определена.

Для символа, интеграла и типов параметра даты/времени, процента и преобразований разделителя строки, точность не применима; если точность будет обеспечена, то будет выдано исключение.

Индекс параметра

Индекс параметра является десятичным целым числом, указывающим на позицию параметра в списке параметров. На первый параметр ссылаются "1$", на второй - "2$" и т.д.

Другой способ сослаться на параметры позицией состоит в том, чтобы использовать флаг '<' ('\u003c'), который заставляет снова использовать параметр предыдущий спецификатора формата. Например, следующие два оператора произвели бы идентичные строки:

  • format("Duke's Birthday: %1$tm %1$te,%1$tY", d)
  • format("Duke's Birthday: %1$tm %<te,%<tY", d)

Детали

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

Любые символы, не явно определенные как преобразования, суффиксы преобразования даты/времени, или флаги, недопустимы и резервируются для будущих расширений.

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

Если спецификатор формата содержит символ преобразования, который не применим к соответствующему параметру, то форматирование не будет произведено.

Общее

Следующие общие преобразования могут быть применены к любому типу параметра:

'b'

'\u0062'

Производит либо "true", либо "false".

Если параметр null, тогда результат "false". Иначе результат "true".  

'B'

'\u0042'

Прописная разновидность 'b'.

'h'

'\u0068'

Производит строку, представляющую значение хэш-кода объекта.  

'H'

'\u0048'

Прописная разновидность 'h'.

's'

'\u0073'

Производит строку.

Если параметр null, тогда результат "null". Иначе параметр конвертируется в Строку.

'S'

'\u0053'

Прописная разновидность 's'.

Следующие флаги применяются к общим преобразованиям:

'-'

'\u002d'

Левый знак выравнивает по ширине вывод. Пробелы ('\u0020') будут добавлены в конце преобразованного значения, как требуется, чтобы заполнить минимальную ширину поля. Если ширина не предоставляется, то форматрирование не будет выполнено. Если этот флаг не дан, то вывод будет выровнен по правому знаку.

'#'

'\u0023'

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

Ширина является минимальным числом символов, которые будут записаны в вывод. Если длина преобразованного значения будет меньше, чем ширина тогда, то вывод будет дополнен ' ' ('\u0020'), пока общее количество символов не будет равняться ширине. Дополнение слева по умолчанию. Если дается флаг '-', тогда дополнение будет справа. Если ширина не определяется, тогда нет никакого минимума.

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

Числовой

Числовые преобразования делятся на следующие категории:

1. Целочисленный и Длинный

2. Плавающая точка и Двойной

Числовые типы будут отформатированы согласно следующему алгоритму:

Алгоритм локализации чисел

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

1. Каждый символ цифры d в строке заменяется специфичной для локали цифрой, вычисленной относительно нулевой цифры z текущей локали; это - d - '0'  + z.

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

3. Если дается флаг ',' ('\u002c'), тогда вставляется специфичный для локали разделитель группировки, сканируя целую часть строки от менее значимых до более значимых цифр и вставляя разделитель с промежутками, определенными размером группировки локали.

4. Если дается флаг '0', тогда специфичные для локали нулевые цифры вставляются после символа знака, если таковые вообще имеются, и перед первой ненулевой цифрой, пока длина строки не равна требуемой ширине поля.

5. Если значение отрицательно и дается флаг '(', тогда a '(' ('\u0028') добавляется к началу и a ')' ('\u0029') добавляется к концу.

6. Если значение отрицательно (или отрицательный нуль с плавающей точкой) и не дается флаг '(', тогда a '-' ('\u002d') добавляется к началу.

7. Если дается флаг '+', и значение положительное или нуль (или положительный нуль с плавающей точкой), тогда a '+' ('\u002b') будет добавляться к концу.

Если значением будет NaN или положительная бесконечность, литеральные строки "NaN" или "Бесконечность" соответственно, то будет вывод. Если значение будет отрицательной бесконечностью, то вывод будет "(Бесконечность)", если дается флаг '(', иначе вывод будет "-Бесконечность". Эти значения не локализуются.

Целочисленное и длинное

Следующие преобразования можно применить к Целочисленным и Длинным значениям.

'd'

'\u0054'

Форматирует параметр как десятичное целое число. Применяется алгоритм локализации.

Если '0' флаг дается, и значение отрицательно, тогда нулевое дополнение произойдет после знака.

'o'

'\u006f'

Форматирует параметр как целое число в основе восемь. Никакая локализация не применяется.  

Если x будет отрицателен, тогда результатом будет значение без знака, сгенерированное путем добавления 2n к значению, где n - число битов в типе, как возвращено статическим полем SIZE в классы Целочисленное или Длинное соответственно.

Если дается флаг '#', тогда вывод будет всегда начинаться с индикатора основания '0'.

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

'x'

'\u0078'

Форматирует параметр как целое число в основе шестнадцать. Никакая локализация не применяется.

Если x будет отрицателен, тогда результатом будет значение без знака, сгенерированное путем добавления 2n к значению, где n - число битов в типе, как возвращено статическим полем SIZE в классы Целочисленное или Длинное соответственно.

Если дается флаг '#', тогда вывод будет всегда начинаться с индикатора основания "0x".

Если дается флаг '0', вывод будет дополнен начальными нулями к ширине поля после индикатора основания или знака (если есть).

'X'

'\u0058'

Прописная разновидность 'x'. Вся строка, представляющая число, будет преобразована в верхний регистр, включая 'x' (если есть) и все шестнадцатеричные цифры 'a' - 'f' ('\u0061' - '\u0066').

Если преобразование 'o', 'x', или 'X' и даются оба флага '#' и '0', тогда результат будет содержать индикатор основания ('0' для восьмеричного и "0x" или "0X" для шестнадцатеричного), некоторое число нулей (на базе ширины) и значение.

Если флаг '-' не дается, тогда дополнение пространства произойдет перед знаком.

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

'+'

'\u002b'

Требует, чтобы вывод включал положительный знак для всех положительных чисел. Если этот флаг не будет дан, тогда только отрицательные величины будут включать знак.

' '

'\u0020'

Требует, чтобы вывод включал единственное дополнительное пространство ('\u0020') для неотрицательных значений.

'0'

'\u0030'

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

','

'\u002c'

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

'('

'\u0028'

Требует, чтобы вывод добавлял к к отрицательным значениям '(' ('\u0028') в начале и a ')' ('\u0029') в конце.

Если никакие флаги не даются, форматирование по умолчанию следующие:

  • Вывод выровнен по правому знаку в пределах ширины
  • Отрицательные числа начинаются с a '-' ('\u002d')
  • Положительные числа и нуль не включают знак или дополнительное ведущее пространство
  • Разделители группировки не включаются

Ширина является минимальным числом символов, которые будут записаны в вывод. Это включает любые знаки, цифры, разделители группировки, индикатор основания и круглые скобки. Если длина преобразованного значения меньше, чем ширина, тогда вывод будет дополнен пробелами ('\u0020'), чтобы общее количество символов равнялось ширине. Дополнение находится слева по умолчанию. Если дается флаг '-', тогда дополнение будет справа. Если ширина не определена, тогда нет никакого минимума.

Точность не применима.

Плавающая точка и двойное

Следующие преобразованиям можно применить к значениям Плавающая точка и Двойное.

'e'

'\u0065'

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

Форматирование величины m зависит от ее значения.

Если m - это NaN или бесконечное, то будут выведены литеральные строки "NaN" или "Бесконечность" соответственно. Эти значения не локализуются.

Если m - положительный нуль или отрицательный нуль, то экспонент будет "+00".

Иначе результатом является строка, которая представляет знак и величину (абсолютное значение) параметра. Форматирование знака описывается в алгоритме локализации. Форматирование величины m зависит от ее значения.

Пусть n быть уникальным целым числом так, что 10n <= м. <10n+1; тогда пусть оно будет математически точным частным m и 10n так, чтобы 1 <= <10. Величина тогда представляется как целая часть a, как единственная десятичная цифра со стоящим после нее десятичным разделителем и десятичными цифрами, представляющими дробную часть a, после которых стоит символ экспонента 'e' ('\u0065'), знак экспонента и представлением n как десятичного целого числа, дополненного нулем, чтобы включать по крайней мере две цифры.

Число цифр в результате дробной части m или a равно точности. Если точность не определяется? тогда значение по умолчанию - 6. Если точность меньше количества цифр, которые появились бы после десятичной точки в строке, тогда значение округляется, используя круглую половину алгоритма. Иначе могут быть добавлены нули, чтобы достигнуть точности.

'E'

'\u0045'

Прописная разновидность 'e'. Символ экспоненты будет 'E' ('\u0045').

'g'

'\u0067'

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

После округления для точности, форматирование получающейся величины m зависит от его значения.

Если m больше или равно 10-4, но меньше 10precision, тогда оно представляется в десятичном формате.

Если m меньше 10-4 или больше или равно 10precision, тогда оно представляется в компьютеризированном экспоненциальном представлении.

Общее количество существенных цифр в m равно точности. Если точность не определена, то значение по умолчанию - 6. Если точность 0, тогда берется 1.

'G'

'\u0047'

Прописная разновидность 'g'.

'f'

'\u0066'

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

Результатом является строка, которая представляет знак и величину (абсолютное значение) параметра. Форматирование знака описывается в алгоритме локализации. Форматирование величины m зависит от его значения.

Если m - NaN или бесконечное, будут выведены литеральные строки "NaN" или "Бесконечность" соответственно. Эти значения не локализуются.

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

Число цифр в результате дробной части m или a равно точности. Если точность не определяется, тогда значение по умолчанию - 6. Если точность меньше числа цифр, которые появились бы после десятичной точки в строке, тогда значение округляется, используя круглую половину алгоритма. Иначе могут быть добавлены нули, чтобы достигнуть точности.

'a'

'\u0061'

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

Результатом является строка, которая представляет знак и величину (абсолютное значение) параметра x.

Если x будет отрицателен или иметь отрицательное нулевое значение, тогда результат начнется с '-' ('\u002d').

Если x будет положителен или иметь положительное нулевое значение и дается флаг '+', тогда результат начнется с '+' ('\u002b').

Форматирование величины m зависит от ее значения.

  • Если значением будет NaN или бесконечность, то будут выведены литеральные строки "NaN" или "Бесконечность", соответственно.
  • Если m является нулем, тогда оно представляется строкой "0x0.0p0".
  • Если m является двойным значение с нормализованным представлением, тогда используются подстроки, чтобы представить поля экспоненты и мантисса. Мантисса представляется символами "0x1." с шестнадцатеричным представлением остальной части мантиссы как дроби. Экспонента представляется 'p' ('\u0070') со стоящей после нее десятичной строкой несмещенной экспоненты, как будто произведенной вызывающей Integer.toString на значении экспоненты.
  • Если m является двойным значение с субнормальным представлением, тогда мантисса представляется символами '0x0.', после которых стоит шестнадцатеричное представление остальной части мантиссы как дроби. Экспонента представляется 'p-1022'. Отметьте, что должна быть по крайней мере одна ненулевая цифра в субнормальной мантиссе.

'A'

'\u0041'

Прописная разновидность 'a'. Вся строка, представляющая число, будет преобразована в верхний регистр, включая 'x' ('\u0078') и 'p' ('\u0070' и все шестнадцатеричные цифры 'a' - 'f' ('\u0061' - '\u0066').

Применяются все флаги, определенные для Целого и Длинного числа.

Если дается флаг '#', тогда будет всегда присутствовать десятичный разделитель.

Если не дается никаких флагов, форматирование по умолчанию следующие:

  • Вывод выровнен по правому знаку в пределах ширины
  • Отрицательные числа начинаются с a '-'
  • Положительные числа и положительный нуль не включают знак или дополнительное ведущее пространство
  • Разделители группировки не включаются
  • Десятичный разделитель появится, только если цифра будет следовать за ним

Ширина является минимальным числом символов, которые будут записаны в вывод. Она включает любые знаки, цифры, групповые разделители, десятичные разделители, экспоненциальный символ, индикатор основания, круглые скобки и строки, представляющие бесконечность и NaN как применимые. Если длина преобразованного значения будет меньше, чем ширина, тогда вывод будет дополнен пробелами ('\u0020'), пока общее количество символов не будет равняться ширине. Дополнение находится слева по умолчанию. Если дается флаг '-', тогда дополнение будет справа. Если ширина не определяется, тогда нет никакого минимума.

Если преобразования - 'e', 'E' или 'f', тогда точность является числом цифр после десятичного разделителя. Если точность не определена, то она условно равна 6.

Если преобразования - 'g' или 'G', тогда точность является общим количеством существенных цифр, присутствующих в величине после округления. Если точность не определена, то значение по умолчанию - 6. Если точность 0, тогда оно равно 1.

Если преобразования - 'a' или 'A', тогда точность является количеством шестнадцатеричных цифр после десятичного разделителя. Если точность не обеспечивается, то будут выведены все цифры.

Дата/время

Это преобразование можно применить к Длинному и Дате.

't'

'\u0074'

Префикс для даты и символов преобразования времени.

'T'

'\u0054'

Прописная разновидность 't'.

Следующие суффиксы символов преобразования времени определяются для преобразования 't' и 'T'.

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

'H'

'\u0048'

Час дня для 24-часовых часов, отформатированный как две цифры с начальным нулем при необходимости, то есть 00 - 23. 00 соответствует полуночи.

'I'

'\u0049'

Час для 12-часовых часов, отформатированных как две цифры с начальным нулем при необходимости, то есть 01 - 12. 01 соответствует одному часу (утро или день).

'k'

'\u006b'

Час дня для 24-часовых часов, то есть 0 - 23. 0 соответствует полуночи.

'l'

'\u006c'

Час для 12-часовых часов, то есть 1 - 12. 1 соответствует одному часу (или утро или день).

'M'

'\u004d'

Минута в течение часа, отформатированного как две цифры с начальным нулем при необходимости, то есть 00 - 59.

'S'

'\u0053'

Секунды в течение минуты, отформатированные как две цифры с начальным нулем при необходимости, то есть 00 - 60 ("60" -специальное значение, требуемое для поддержки потерянной секунды).

'L'

'\u004c'

Миллисекунда в пределах секунды, отформатированная как три цифры с начальными нулями при необходимости, то есть 000 - 999.

'N'

'\u004e'

Наносекунда в пределах секунды, отформатированная как девять цифр с начальными нулями при необходимости, то есть 000000000 - 999999999. Точность этого значения ограничивается разрешением базовой операционной системы или аппаратных средств.

'p'

'\u0070'

Специфичный для локали маркер утра или дня в нижнем регистре, например, "am" или "pm". Использование префикса преобразования 'T' переводит этот вывод в верхний регистр.

'z'

'\u007a'

Числовое смещение часового пояса стиля RFC 822 от GMT, например 0800.

'Z'

'\u005a'

Строка, представляющая аббревиатуру часового пояса.

's'

'\u0073'

Секунды с начала эпохи, начинающейся 1 января 1970 00:00:00 UTC, то есть минимальное подписанное 64-битовое целое число, разделенное на 1000, до максимального подписанного 64-битового целого числа, разделенного на 1000.

'Q'

'\u004f'

Миллисекунды с начала эпохи, начинающейся 1 января 1970 00:00:00 UTC, то есть минимальное подписанное 64-битовое целое число, разделенное на 1000, до максимального подписанного 64-битового целого числа, разделенного на 1000. Точность этого значения ограничивается разрешением базовой операционной системы или аппаратных средств.

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

'B'

'\u0042'

Специфичное для локали полное имя месяца, например, "январь", "февраль".

'b'

'\u0062'

Специфичное для локали сокращенное имя месяца, например, "янв", "фев".

'h'

'\u0068'

То же самое, как 'b'.

'A'

'\u0041'

Специфичное для локали полное имя дня недели, например, "воскресенье", "понедельник"

'a'

'\u0061'

Специфичное для локали краткое название дня недели, например, "вск", "пон"

'C'

'\u0043'

Год из четырех знаков, разделенный на 100, отформатированный как две цифры с начальным нулем при необходимости, то есть 00 - 99

'Y'

'\u0059'

Год, отформатированный по крайней мере к четырем цифрам с начальными нулями при необходимости, например, 0092 равняется 92 CE по Григорианскому календарю.

'y'

'\u0079'

Последние две цифры года, отформатированного с начальными нулями при необходимости, то есть 00 - 99.

'j'

'\u006a'

День года, отформатированного как три цифры с начальными нулями при необходимости, например 001 - 366 по Григорианскому календарю. 001 соответствует первому дню года.

'm'

'\u006d'

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

'd'

'\u0064'

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

'e'

'\u0065'

День месяца, отформатированного как две цифры, то есть 1 - 31, где "1" - первый день месяца.

Следующие символы преобразования используются для того, чтобы отформатировать общие составы даты/времени.

'R'

'\u0052'

Время, отформатированное для 24-часовых часов как "%tH:%tM"

'T'

'\u0054'

Время, отформатированное для 24-часовых часов как "%tH:%tM:%tS".

'r'

'\u0072'

Время, отформатированное для 12-часовых часов как "%tI:%tM:%tS %Tp". Расположение маркера утра или дня ('%Tp') может быть зависимым от локали.

'D'

'\u0044'

Дата, отформатированная как "%tm/%td/%ty".

'F'

'\u0046'

Полная дата ISO 8601, отформатированная как "%tY-%tm-%td".

'c'

'\u0063'

Дата и время, отформатированное как "%ta %tb %td %tT %tZ %tY", например "Sun Jul 20 16:17:00 EDT 1969".

Применяется флаг '-', определенный для Общих преобразований. Если дается флаг '#', тогда форматирование не выполняется.

Ширина является минимальным количеством символов, которые будут записаны в вывод. Если длина преобразованного значения меньше, чем ширина, тогда вывод будет дополнен пробелами ('\u0020'), пока общее количество символов не будет равняться ширине. Дополнение слева по умолчанию. Если дается флаг '-', тогда дополнение будет справа. Если ширина не определяется, тогда нет никакого минимума.

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

Процент

Преобразование не соответствует никакому параметру.

'%'

Результатом является литерал '%' ('\u0025')

Ширина является минимальным числом символов, которые будут записаны в вывод, включая '%'. Если длина преобразованного значения меньше, чем ширина, тогда вывод будет дополнен пробелами ('\u0020'), пока общее количество символов не будет равняться ширине. Дополнение слева. Если ширина не определяется, тогда выводится только '%'.

Применяется флаг '-', определенный для Общих преобразований, применяется.

Точность не применима.

Разделитель строки

Преобразование не соответствует никакому параметру.

'n'

специфичный для платформы разделитель строки

Флаги, ширина и точность не применимы.

Индекс параметра

Спецификаторы формата могут сослаться на параметры тремя способами:

  • Явная индексация используется, когда спецификатор формата содержит индекс параметра. Индекс параметра является десятичным целым числом, указывающим на позицию параметра в списке параметров. На первый параметр ссылаеются "1$", на второй - "2$" и т.д. На параметр можно сослаться не раз.  

Например:

format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s", "a", "b", "c", "d")

имеет результатом

d c b a d c b a

Relative indexing is used when the format specifier contains a '<' ('\u003c') flag which causes the argument for the previous format specifier to be re-used. If there is no previous argument, then formatting will fail. Относительная индексация используется, когда спецификатор формата содержит флвг a '<' ('\u003c'), который заставляет снова использовать параметр предыдущего спецификатора формата. Если нет никакого предыдущего параметра, то форматирование не выполняется.

format("%s %s %<s %<s", "a", "b", "c", "d")

имеет результатом

a b b b

Параметры "c" and "d" игнорируются, потому что на них не ссылаются.

  • Обычная индексация используется, когда спецификатор формата не содержит ни индекса параметра, ни флага a '<'. Каждый спецификатор формата, который использует обычную индексацию, получает последовательный неявный индекс в списке параметров, который не зависит от индексов, используемых явной или относительной индексацией.

format("%s %s %s %s", "a", "b", "c", "d")

имеет результатом

a b c d

Возможно иметь строку формата, которая использует все формы индексации, например:

format("%2$s %s %<s %<s", "a", "b", "c", "d")

имеет результатом

b a a b

Параметры "c" и "d" игнорируются. потому что на них не ссылаются.

Если индекс параметра не соответсвует существующим параметрам, форматирование не выполняется.

Если параметров больше, чем спецификаторов формата, дополнительные параметры игнорируются.