Класс Formatter

java.lang.Object

java.util.Formatter

Все реализованные интерфейсы:: Closeable, Flushable, AutoCloseable

public final class Formatter extends Object implements Closeable, Flushable

Интерпретатор строк формата в стиле printf. Этот класс предоставляет поддержку выравнивания и размещения текста, общие форматы для числовых, строковых и данных даты/времени, а также локально-зависимый вывод. Поддерживаются стандартные типы Java, такие как byte, BigDecimal, и Calendar. Ограниченная настройка форматирования для произвольных типов пользователя предоставляется через интерфейс Formattable.

Форматеры не обязательно безопасны для многопоточного доступа. Обеспечение потоковой безопасности является опциональным и лежит на ответственности пользователей методов этого класса.

Форматированный вывод для языка Java сильно вдохновлен printf языка C. Хотя строки формата похожи на строки C, некоторые изменения были внесены для соответствия языку Java и использования некоторых его возможностей. Также форматирование в Java более строгое, чем в C; например, если преобразование несовместимо с флагом, будет брошено исключение. В C несоответствующие флаги игнорируются без сообщений об ошибках. Следовательно, строки формата предназначены для понимания программистами C, но не обязательно полностью совместимы со строками формата в C.

Примеры ожидаемого использования:

   StringBuilder sb = new StringBuilder();
   // Send all output to the Appendable object sb
   Formatter formatter = new Formatter(sb, Locale.US);

   // Explicit argument indices may be used to re-order output.
   formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
   // -> " d  c  b  a"

   // Optional locale as the first argument can be used to get
   // locale-specific formatting of numbers.  The precision and width can be
   // given to round and align the value.
   formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E);
   // -> "e =    +2,7183"

   // The '(' numeric flag may be used to format negative numbers with
   // parentheses rather than a minus sign.  Group separators are
   // automatically inserted.
   formatter.format("Amount gained or lost since last statement: $ %(,.2f",
                    balanceDelta);
   // -> "Amount gained or lost since last statement: $ (6,217.58)"

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

   // Writes a formatted string to System.out.
   System.out.format("Local time: %tT", Calendar.getInstance());
   // -> "Local time: 13:34:18"

   // Writes formatted output to System.err.
   System.err.printf("Unable to open file '%1$s': %2$s",
                     fileName, exception.getMessage());
   // -> "Unable to open file 'food': No such file or directory"

Как и в sprintf(3) языке C, строки можно форматировать с помощью статического метода String.format:

   // Format a string containing a date.
   import java.util.Calendar;
   import java.util.GregorianCalendar;
   import static java.util.Calendar.*;

   Calendar c = new GregorianCalendar(1995, MAY, 23);
   String s = String.format("Duke's Birthday: %1$tb %1$te, %1$tY", c);
   // -> s == "Duke's Birthday: May 23, 1995"

Организация

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

Обзор

Этот раздел предназначен для краткого обзора понятий форматирования. Для точного описания поведения см. раздел Подробности.

Синтаксис строк формата

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

   Calendar c = ...;
   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);

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

Спецификаторы формата для общих, символьных и числовых типов имеют следующий синтаксис:
```
   %[argument_index$][flags][width][.precision]conversion
 
```
Необязательный индекс_аргумента — это целое десятичное число, указывающее позицию аргумента в списке аргументов. Первый аргумент обозначается "1$", второй — "2$" и так далее.

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

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

Необязательная точность — это неотрицательное целое десятичное число, обычно используемое для ограничения количества символов. Конкретное поведение зависит от преобразования.

Обязательное преобразование — это символ, указывающий, как должен быть отформатирован аргумент. Набор допустимых преобразований для данного аргумента зависит от типа данных аргумента.
Спецификаторы формата для типов, используемых для представления дат и времени, имеют следующий синтаксис:
```
   %[argument_index$][flags][width]conversion
 
```
Необязательные индекс_аргумента, флаги и ширина определяются так же, как и выше.

Обязательное преобразование — это последовательность из двух символов. Первый символ — 't' или 'T'. Второй символ указывает используемый формат. Эти символы похожи на, но не полностью идентичны, символам, определённым в GNU date и POSIX strftime(3c).
Спецификаторы формата, которые не соответствуют аргументам, имеют следующий синтаксис:
```
   %[flags][width]conversion
 
```
Необязательные флаги и ширина определяются так же, как и выше.

Обязательное преобразование — это символ, указывающий текст, который должен быть вставлен в вывод.

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

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

Общие — могут быть применены к любому типу аргумента
Символьные — могут быть применены к базовым типам, которые представляют символы Юникода: char, Character, byte, Byte, short, и Short. Это преобразование также может быть применено к типам int и Integer, когда Character.isValidCodePoint(int) возвращает true
Числовые
1. Целочисленные — могут быть применены к целочисленным типам Java: byte, Byte, short, Short, int и Integer, long, Long, и BigInteger (но не char или Character)
2. С плавающей точкой — может быть применён к типам с плавающей точкой Java: float, Float, double, Double, и BigDecimal
Дата/Время — может быть применён к типам Java, способным кодировать дату или время: long, Long, Calendar, Date и TemporalAccessor
Процент — производит литерал '%' ('\u0025')
Разделитель строк — производит платформенно-зависимый разделитель строк

Для категорий Общие, Символьные, Числовые, Целочисленные и Дата/Время преобразования, если не указано иное, если аргумент arg равен null, то результатом является "null".

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

genConv
Преобразование	Категория аргумента	Описание
`'b'`, `'B'`	общее	Если аргумент arg имеет тип `null`, то результатом будет "`false`". Если arg является `boolean` или `Boolean`, то результатом является строка, возвращаемая методом `String.valueOf(arg)`. В противном случае результатом будет "true".
`'h'`, `'H'`	общее	Результат получается путем вызова `Integer.toHexString(arg.hashCode())`.
`'s'`, `'S'`	общее	Если arg реализует интерфейс `Formattable`, то вызывается метод `arg.formatTo`. В противном случае результат получается путем вызова `arg.toString()`.
`'c'`, `'C'`	символ	Результатом является символ Unicode
`'d'`	целочисленный	Результат форматируется как десятичное целое число
`'o'`	целочисленный	Результат форматируется как восьмеричное целое число
`'x'`, `'X'`	целочисленный	Результат форматируется как шестнадцатеричное целое число
`'e'`, `'E'`	с плавающей точкой	Результат форматируется как десятичное число в компьютерной научной записи
`'f'`	с плавающей точкой	Результат форматируется как десятичное число
`'g'`, `'G'`	с плавающей точкой	Результат форматируется с использованием компьютерной научной записи или десятичного формата, в зависимости от точности и значения после округления.
`'a'`, `'A'`	с плавающей точкой	Результат форматируется как шестнадцатеричное число с плавающей точкой с мантиссой и показателем степени. Это преобразование не поддерживается для типа `BigDecimal` несмотря на то, что последний находится в категории аргументов с плавающей точкой.
`'t'`, `'T'`	дата/время	Префикс для символов преобразования даты и времени. См. Преобразования даты и времени.
`'%'`	процент	Результатом является литерал `'%'` (`'\u0025'`)
`'n'`	разделитель строки	Результатом является разделитель строк, специфичный для платформы

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

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

Следующие символы суффиксов преобразования даты и времени определены для преобразований 't' и 'T'. Типы похожи на, но не полностью идентичны, типам, определенным в GNU date и POSIX strftime(3c). Добавлены типы преобразований для доступа к функциям, специфичным для Java (например, 'L' для миллисекунд в секунде).

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

time
`'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'`	Численный смещение часового пояса от GMT в стиле RFC 822, например, `-0800`. Это значение будет корректироваться по необходимости для летнего времени. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для этой инстанции виртуальной машины Java.
`'Z'`	Строка, представляющая аббревиатуру часового пояса. Это значение будет корректироваться по необходимости для летнего времени. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для этой инстанции виртуальной машины Java. Язык среды Formatter будет иметь приоритет над языком среды аргумента (если таковой имеется).
`'s'`	Секунды с начала эпохи, начиная с 1 января 1970 `00:00:00` UTC, т.е. `Long.MIN_VALUE/1000` до `Long.MAX_VALUE/1000`.
`'Q'`	Миллисекунды с начала эпохи, начиная с 1 января 1970 `00:00:00` UTC, т.е. `Long.MIN_VALUE` до `Long.MAX_VALUE`.

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

date
`'B'`	Полное название месяца в формате языка среды, например `"January"`, `"February"`.
`'b'`	Сокращенное название месяца в формате языка среды, например `"Jan"`, `"Feb"`.
`'h'`	То же, что и `'b'`.
`'A'`	Полное название дня недели в формате языка среды, например `"Sunday"`, `"Monday"`
`'a'`	Сокращенное название дня недели в формате языка среды, например `"Sun"`, `"Mon"`
`'C'`	Четырехзначный год, деленный на `100`, форматированный как двухзначное число с ведущим нулём по мере необходимости, например, `00 - 99`
`'Y'`	Год, форматируется как минимум четырьмя цифрами с ведущими нулями по мере необходимости, например, `0092` равно `92` до н.э. для григорианского календаря.
`'y'`	Последние две цифры года, форматируются с ведущими нулями по мере необходимости, например, `00 - 99`.
`'j'`	День года, форматируется как трехзначное число с ведущими нулями по мере необходимости, например, `001 - 366` для григорианского календаря.
`'m'`	Месяц, форматируется как двухзначное число с ведущим нулём по мере необходимости, например, `01 - 13`.
`'d'`	День месяца, форматируется как двухзначное число с ведущим нулём по мере необходимости, например, `01 - 31`
`'e'`	День месяца, форматируется как двухзначное число, например, `1 - 31`.

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

composites
`'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 означает, что флаг поддерживается для указанных типов аргументов.

genConv
Флаг	Общий	Символ	Целое	Вещественное	Дата/Время	Описание
'-'	y	y	y	y	y	Результат будет выровнен влево.
'#'	y¹	-	y³	y	-	Результат должен использовать альтернативную форму, зависящую от преобразования
'+'	-	-	y⁴	y	-	Результат всегда будет содержать знак
' '	-	-	y⁴	y	-	Результат будет содержать ведущий пробел для положительных значений
'0'	-	-	y	y	-	Результат будет заполнен нулями
','	-	-	y²	y⁵	-	Результат будет содержать разделители группировки, специфичные для локали разделители группировки
'('	-	-	y⁴	y⁵	-	Результат будет заключать отрицательные числа в скобки

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

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

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

⁴ Для преобразований 'd', 'o', 'x' и 'X', применённых к BigInteger или 'd' применённых к byte, Byte, short, Short, int и Integer, long и Long.

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

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

Ширина

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

Точность

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

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

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

Индекс аргумента

Индекс аргумента — это десятичное целое число, указывающее позицию аргумента в списке аргументов. Первый аргумент обозначается «1$», второй — «2$» и т. д.

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

   Calendar c = ...;
   String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);

   String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);

Подробности

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

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

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

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

Значения точности должны находиться в диапазоне от нуля до Integer.MAX_VALUE включительно, в противном случае будет выброшено IllegalFormatPrecisionException.

Значения ширины должны находиться в диапазоне от одного до Integer.MAX_VALUE включительно, в противном случае будет выброшено IllegalFormatWidthException. Обратите внимание, что ширина может иметь отрицательное значение, но знак минус является флагом. Например, в строке формата "%-20s" ширина равна 20, а флаг — «-».

Значения индекса должны находиться в диапазоне от одного до Integer.MAX_VALUE включительно, в противном случае будет выброшено IllegalFormatException.

Все указанные исключения могут быть выброшены любыми из методов format класса Formatter, а также любыми удобными методами format, такими как String.format и PrintStream.printf.

Для преобразований категорий Общие, Символы, Числа, Целые и Дата/Время, если аргумент arg равен null, результат равен «null».

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

Общие

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

dgConv
`'b'`	`'\u0062'`	Производит либо "`true`", либо "`false`", как возвращает `Boolean.toString(boolean)`. Если аргумент — `null`, то результат — "`false`". Если аргумент — `boolean` или `Boolean`, то результат — строка, возвращаемая `String.valueOf()`. В противном случае результат — "`true`". Если задан флаг `'#'`, то будет брошено исключение `FormatFlagsConversionMismatchException`.
`'B'`	`'\u0042'`	Версия аргумента `'b'` в верхнем регистре.
`'h'`	`'\u0068'`	Производит строку, представляющую значение хэш-кода объекта. Результат получается вызовом `Integer.toHexString(arg.hashCode())`. Если задан флаг `'#'`, то будет брошено исключение `FormatFlagsConversionMismatchException`.
`'H'`	`'\u0048'`	Версия аргумента `'h'` в верхнем регистре.
`'s'`	`'\u0073'`	Производит строку. Если аргумент реализует `Formattable`, то вызывается его метод `formatTo`. В противном случае результат получается вызовом метода `toString()` аргумента. Если задан флаг `'#'` и аргумент не является `Formattable`, то будет брошено исключение `FormatFlagsConversionMismatchException`.
`'S'`	`'\u0053'`	Версия аргумента `'s'` в верхнем регистре.

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

dFlags
`'-'`	`'\u002d'`	Выравнивает вывод влево. Пробелы (`'\u0020'`) будут добавлены в конец преобразованного значения по мере необходимости для заполнения минимальной ширины поля. Если ширина не указана, то будет брошено исключение `MissingFormatWidthException`. Если этот флаг не задан, то вывод будет выровнен по правому краю.
`'#'`	`'\u0023'`	Требует, чтобы вывод использовал альтернативную форму. Определение формы задается преобразованием.

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

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

Символ

Это преобразование может быть применено к char и Character. Оно также может быть применено к типам byte, Byte, short, и Short, int и Integer, когда Character.isValidCodePoint(int) возвращает true. Если возвращает false, то будет брошено исключение IllegalFormatCodePointException.

charConv
`'c'`	`'\u0063'`	Форматирует аргумент как символ Юникода, как описано в Представлении символов Юникода. Это может быть более одного 16-битного `char` в случае, когда аргумент представляет дополнительный символ. Если задан флаг `'#'`, то будет брошено исключение `FormatFlagsConversionMismatchException`.
`'C'`	`'\u0043'`	Версия аргумента `'c'` в верхнем регистре.

Флаг '-', определенный для Общих преобразований, применяется. Если задан флаг '#', то будет брошено исключение FormatFlagsConversionMismatchException.

Ширина определяется так же, как для Общих преобразований.

Точность неприменима. Если точность указана, то будет брошено исключение IllegalFormatPrecisionException.

Числовые

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

Байт, Короткое, Целое и Длинное
BigInteger
Float и Double
BigDecimal

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

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

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

Каждый символ цифры d в строке заменяется локально-специфичной цифрой, вычисленной относительно нулевой цифры текущей локали z; то есть d - '0' + z.
Если присутствует десятичная точка, подставляется десятичная точка, специфичная для данной локали.
Если задан флаг ',' ('\u002c') флага, то локально-специфичный разделитель групп вставляется путем сканирования целой части строки справа налево и вставки разделителя через интервалы, определенные размером группировки локали grouping size.
Если задан флаг '0', то локально-специфичные нулевые цифры вставляются после знака, если таковой имеется, и перед первой ненулевой цифрой до тех пор, пока длина строки не станет равна запрошенной ширине поля.
Если значение отрицательно, и задан флаг '(', то добавляется символ '(' ('\u0028') в начало и ')' ('\u0029') в конец.
Если значение отрицательное (или плавающая запятая отрицательный ноль) и флаг '(' не задан, то в начале добавляется '-' ('\u002d')
Если задан флаг '+' и значение положительное или ноль (или плавающая запятая положительный ноль), то в начало добавляется '+' ('\u002b').

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

Байт, Короткое, Целое и Длинное

Следующие преобразования могут быть применены к byte, Byte, short, Short, int и Integer, long, и Long.

IntConv
`'d'`	`'\u0064'`	Форматирует аргумент в виде десятичного целого числа. Применяется алгоритм локализации. Если задан флаг `'0'` и значение отрицательно, то нулевое заполнение произойдёт после знака. Если задан флаг `'#'`, то будет брошено исключение `FormatFlagsConversionMismatchException`.
`'o'`	`'\u006f'`	Форматирует аргумент как целое число в восьмеричной системе счисления. Локализация не применяется. Если x отрицательно, результат будет беззнаковым значением, полученным путём добавления 2ⁿ к значению, где `n` — количество битов в типе, возвращаемое статическим полем `SIZE` в классах Byte, Short, Integer или Long соответственно. Если задан флаг `'#'`, вывод всегда будет начинаться с индикатора системы счисления `'0'`. Если задан флаг `'0'`, вывод будет дополнен ведущими нулями до ширины поля после любого указания знака. Если заданы флаги `'('`, `'+'`, ' ', или `','`, будет брошено исключение `FormatFlagsConversionMismatchException`.
`'x'`	`'\u0078'`	Форматирует аргумент как целое число в шестнадцатеричной системе счисления. Локализация не применяется. Если x отрицательно, результат будет беззнаковым значением, полученным путём добавления 2ⁿ к значению, где `n` — количество битов в типе, возвращаемое статическим полем `SIZE` в классах Byte, Short, Integer или Long соответственно. Если задан флаг `'#'`, вывод всегда будет начинаться с индикатора системы счисления `"0x"`. Если задан флаг `'0'`, вывод будет дополнен ведущими нулями до ширины поля после индикатора системы счисления или знака (если он присутствует). Если заданы флаги `'('`, `' '`, `'+'`, или `','`, будет брошено исключение `FormatFlagsConversionMismatchException`.
`'X'`	`'\u0058'`	Версия с заглавными буквами для `'x'`. Весь строковый текст, представляющий число, будет преобразован в верхний регистр, включая `'x'` (если есть) и все шестнадцатеричные цифры `'a'` - `'f'` (`'\u0061'` - `'\u0066'`).

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

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

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

intFlags
`'+'`	`'\u002b'`	Требует, чтобы вывод включал знак «плюс» для всех положительных чисел. Если этот флаг не задан, знак будет присутствовать только у отрицательных значений. Если заданы оба флага `'+'` и `' '`, будет брошено исключение `IllegalFormatFlagsException`.
`' '`	`'\u0020'`	Требует включения дополнительного пробела (`'\u0020'`) для неотрицательных значений. Если заданы оба флага `'+'` и `' '`, будет брошено исключение `IllegalFormatFlagsException`.
`'0'`	`'\u0030'`	Требует дополнения вывода ведущими нулями до минимальной ширины поля после любого знака или индикатора системы счисления, кроме случаев преобразования NaN или бесконечности. Если ширина не указана, будет брошено исключение `MissingFormatWidthException`. Если заданы оба флага `'-'` и `'0'`, будет брошено исключение `IllegalFormatFlagsException`.
`','`	`'\u002c'`	Требует включения разделителей групп, специфичных для локали, как описано в разделе «группировка» алгоритма локализации.
`'('`	`'\u0028'`	Требует добавления `'('` (`'\u0028'`) перед отрицательными значениями и `')'` (`'\u0029'`) после них.

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

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

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

Точность не применима. Если точность указана, будет брошено исключение IllegalFormatPrecisionException.

BigInteger

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

bIntConv
`'d'`	`'\u0064'`	Требует форматирования вывода в виде десятичного целого числа. Применяется алгоритм локализации. Если задан флаг `'#'`, будет брошено исключение `FormatFlagsConversionMismatchException`.
`'o'`	`'\u006f'`	Требует форматирования вывода как целого числа в восьмеричной системе счисления. Локализация не применяется. Если x отрицательно, результат будет знаковым значением, начинающимся с `'-'` (`'\u002d'`). Знаковый вывод разрешён для этого типа, потому что в отличие от примитивных типов, невозможно создать беззнаковый эквивалент без предположения явного размера типа данных. Если x положительно или равно нулю, и задан флаг `'+'`, результат начнется с `'+'` (`'\u002b'`). Если задан флаг `'#'`, вывод всегда будет начинаться с префикса `'0'`. Если задан флаг `'0'`, вывод будет дополнен ведущими нулями до ширины поля после любого указания знака. Если задан флаг `','`, будет брошено исключение `FormatFlagsConversionMismatchException`.
`'x'`	`'\u0078'`	Требует форматирования вывода как целого числа в шестнадцатеричной системе счисления. Локализация не применяется. Если x отрицательно, результат будет знаковым значением, начинающимся с `'-'` (`'\u002d'`). Знаковый вывод разрешён для этого типа, потому что в отличие от примитивных типов, невозможно создать беззнаковый эквивалент без предположения явного размера типа данных. Если x положительно или равно нулю, и задан флаг `'+'`, результат начнется с `'+'` (`'\u002b'`). Если задан флаг `'#'`, вывод всегда будет начинаться с индикатора системы счисления `"0x"`. Если задан флаг `'0'`, вывод будет дополнен ведущими нулями до ширины поля после индикатора системы счисления или знака (если он присутствует). Если задан флаг `','`, будет брошено исключение `FormatFlagsConversionMismatchException`.
`'X'`	`'\u0058'`	Версия с заглавными буквами для `'x'`. Весь строковый текст, представляющий число, будет преобразован в верхний регистр, включая `'x'` (если есть) и все шестнадцатеричные цифры `'a'` - `'f'` (`'\u0061'` - `'\u0066'`).

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

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

Если флаг '-' не задан, то заполнение пробелами будет происходить перед знаком.

Применяются все флаги, определенные для Byte, Short, Integer и Long. Поведение по умолчанию при отсутствии флагов такое же, как для Byte, Short, Integer и Long.

Спецификация ширины такая же, как определено для Byte, Short, Integer и Long.

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

Float и Double

Следующие преобразования могут быть применены к float, Float, double и Double.

floatConv
`'e'`	`'\u0065'`	Требуется, чтобы вывод был отформатирован с использованием научной нотации. Применяется алгоритм локализации. Форматирование величины m зависит от её значения. Если m является NaN или бесконечностью, то на выходе будут выводиться литеральные строки "NaN" или "Infinity" соответственно. Эти значения не локализованы. Если m является положительным или отрицательным нулем, то показатель степени будет `"+00"`. В противном случае, результат представляет собой строку, которая отображает знак и величину (абсолютное значение) аргумента. Форматирование знака описано в алгоритме локализации. Форматирование величины m зависит от её значения. Пусть n - единственное целое число такое, что 10ⁿ <= m < 10ⁿ⁺¹; тогда пусть a будет математически точным частным от деления m на 10ⁿ так, что 1 <= a < 10. Величина затем представляется как целая часть a, как одна десятичная цифра, за которой следует десятичный разделитель, за которым следуют десятичные цифры, представляющие дробную часть a, за которыми следует символ экспоненты `'e'` (`'\u0065'`), за которым следует знак экспоненты, за которым следует представление n как десятичного целого числа, как создано методом `Long.toString(long, int)`, и дополненное нулями, чтобы включить не менее двух цифр. Количество цифр в результате для дробной части m или a равно точности. Если точность не указана, то значение по умолчанию равно `6`. Если точность меньше количества цифр, которые будут отображаться после десятичной точки в строке, возвращаемой `Float.toString(float)` или `Double.toString(double)` соответственно, то значение будет округлено с использованием алгоритма округления вверх. В противном случае, для достижения заданной точности могут быть добавлены нули. Для канонического представления значения используйте `Float.toString(float)` или `Double.toString(double)` в зависимости от ситуации. Если задан флаг `','`, то будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'E'`	`'\u0045'`	Вариант в верхнем регистре `'e'`. Символ экспоненты будет `'E'` (`'\u0045'`).
`'g'`	`'\u0067'`	Требуется, чтобы вывод был отформатирован в общей научной нотации, как описано ниже. Применяется алгоритм локализации. После округления для заданной точности, форматирование результирующей величины m зависит от её значения. Если m больше или равно 10^-4, но меньше 10^{точность}, то оно представляется в десятичном формате. Если m меньше 10^-4 или больше или равно 10^{точность}, то оно представляется в научной нотации. Общее количество значащих цифр в m равно точности. Если точность не указана, то значение по умолчанию равно `6`. Если точность `0`, то она принимается равной `1`. Если задан флаг `'#'`, то будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'G'`	`'\u0047'`	Вариант в верхнем регистре `'g'`.
`'f'`	`'\u0066'`	Требуется, чтобы вывод был отформатирован с использованием десятичного формата. Применяется алгоритм локализации. Результат представляет собой строку, которая отображает знак и величину (абсолютное значение) аргумента. Форматирование знака описано в алгоритме локализации. Форматирование величины m зависит от её значения. Если m NaN или бесконечность, то на выходе будут выводиться литеральные строки "NaN" или "Infinity" соответственно. Эти значения не локализованы. Величина форматируется как целая часть m, без ведущих нулей, за которой следует десятичный разделитель, за которым следуют одна или более десятичных цифр, представляющие дробную часть m. Количество цифр в результате для дробной части m или a равно точности. Если точность не указана, то значение по умолчанию равно `6`. Если точность меньше количества цифр, которые будут отображаться после десятичной точки в строке, возвращаемой `Float.toString(float)` или `Double.toString(double)` соответственно, то значение будет округлено с использованием алгоритма округления вверх. В противном случае, для достижения заданной точности могут быть добавлены нули. Для канонического представления значения используйте `Float.toString(float)` или `Double.toString(double)` в зависимости от ситуации.
`'a'`	`'\u0061'`	Требуется, чтобы вывод был отформатирован в шестнадцатеричной экспоненциальной форме. Локализация не применяется. Результат представляет собой строку, которая отображает знак и величину (абсолютное значение) аргумента x. Если x отрицательный или имеет значение отрицательного нуля, то результат будет начинаться с `'-'` (`'\u002d'`). Если x положительный или имеет значение положительного нуля, и задан флаг `'+'`, то результат будет начинаться с `'+'` (`'\u002b'`). Форматирование величины m зависит от её значения. Если значение является NaN или бесконечностью, то на выходе будут выводиться литеральные строки "NaN" или "Infinity" соответственно. Если m равно нулю, то оно представляется строкой `"0x0.0p0"`. Если m является `double` значением с нормализованным представлением, то используются подстроки для представления полей мантиссы и экспоненты. Мантисса представляется символами `"0x1."` с последующим шестнадцатеричным представлением остальной части мантиссы как дроби. Экспонента представляется `'p'` (`'\u0070'`) с последующей десятичной строкой несмещенной экспоненты, как если бы она была получена вызовом `Integer.toString` для значения экспоненты. Если указана точность, значение округляется до заданного количества шестнадцатеричных цифр. Если m является `double` значением с субнормализованным представлением, то, если точность не указана в диапазоне от 1 до 12 включительно, мантисса представляется символами `'0x0.'` с последующим шестнадцатеричным представлением остальной части мантиссы как дроби, а экспонента представляется `'p-1022'`. Если точность находится в интервале [1, 12], субнормализованное значение нормализуется таким образом, чтобы оно начиналось с символов `'0x1.'`, округлялось до количества шестнадцатеричных цифр точности, а экспонента корректировалась соответствующим образом. Обратите внимание, что в субнормализованной мантиссе должна быть хотя бы одна ненулевая цифра. Если заданы флаги `'('` или `','`, то будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'A'`	`'\u0041'`	Вариант в верхнем регистре `'a'`. Вся строка, представляющая число, будет преобразована в верхний регистр, включая `'x'` (`'\u0078'`) и `'p'` (`'\u0070'` и все шестнадцатеричные цифры `'a'` - `'f'` (`'\u0061'` - `'\u0066'`).

Применяются все флаги, определенные для Byte, Short, Integer и Long.

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

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

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

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

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

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

Если преобразование — 'a' или 'A', то точность — это количество шестнадцатеричных цифр после точки. Если точность не указана, будут выведены все цифры, возвращаемые Double.toHexString(double).

BigDecimal

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

floatConv
`'e'`	`'\u0065'`	Требует форматирования вывода с использованием научной записи. Применяется алгоритм локализации. Форматирование величины m зависит от её значения. Если m — положительный или отрицательный ноль, то показатель степени будет `"+00"`. В противном случае результатом будет строка, представляющая знак и абсолютное значение аргумента. Форматирование знака описано в алгоритме локализации. Форматирование величины m зависит от её значения. Пусть n — единственное целое число такое, что 10ⁿ <= m < 10ⁿ⁺¹; тогда пусть a — математически точное частное m и 10ⁿ так, что 1 <= a < 10. Величина представляется затем целой частью a, как одна цифра, за которой следует десятичный разделитель, за которым следуют десятичные цифры, представляющие дробную часть a, за которыми следует символ степени `'e'` (`'\u0065'`), за которым следует знак показателя степени, за которым следует представление n как целого десятичного числа, полученное методом `Long.toString(long, int)`, и дополненное нулями до включения как минимум двух цифр. Количество цифр в результате для дробной части m или a равно точности. Если точность не указана, значение по умолчанию равно `6`. Если точность меньше количества цифр справа от десятичной точки, значение будет округлено с использованием алгоритма округления до ближайшего целого. В противном случае могут быть добавлены нули, чтобы достичь точности. Для канонического представления значения используйте `BigDecimal.toString()`. Если указан флаг `','`, будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'E'`	`'\u0045'`	Заглавная форма `'e'`. Символ степени будет `'E'` (`'\u0045'`).
`'g'`	`'\u0067'`	Требует форматирования вывода в общем виде научной записи, как описано ниже. Применяется алгоритм локализации. После округления для точности, форматирование полученной величины m зависит от её значения. Если m больше или равно 10^-4, но меньше 10^{точность}, то оно представляется в десятичном формате. Если m меньше 10^-4 или больше или равно 10^{точность}, то оно представляется в научной записи. Общее количество значащих цифр в m равно точности. Если точность не указана, значение по умолчанию равно `6`. Если точность `0`, она принимается равной `1`. Если указан флаг `'#'`, будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'G'`	`'\u0047'`	Заглавная форма `'g'`.
`'f'`	`'\u0066'`	Требует форматирования вывода в десятичном формате. Применяется алгоритм локализации. Результатом является строка, представляющая знак и абсолютное значение аргумента. Форматирование знака описано в алгоритме локализации. Форматирование величины m зависит от её значения. Величина форматируется как целая часть m без ведущих нулей, за которой следует десятичный разделитель, за которым следуют одна или несколько десятичных цифр, представляющих дробную часть m. Количество цифр в результате для дробной части m или a равно точности. Если точность не указана, значение по умолчанию равно `6`. Если точность меньше количества цифр справа от десятичной точки, значение будет округлено с использованием алгоритма округления до ближайшего целого. В противном случае могут быть добавлены нули, чтобы достичь точности. Для канонического представления значения используйте `BigDecimal.toString()`.

Все флаги, определённые для Byte, Short, Integer и Long, применяются.

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

Поведение по умолчанию при отсутствии флагов такое же, как у Float и Double.

Указание ширины и точности такое же, как определено для Float и Double.

Дата/Время

Это преобразование может быть применено к long, Long, Calendar, Date и TemporalAccessor

DTConv
`'t'`	`'\u0074'`	Префикс для символов преобразования даты и времени.
`'T'`	`'\u0054'`	Заглавная форма `'t'`.

Следующие символы преобразования даты и времени определены для преобразований 't' и 'T'. Типы похожи, но не полностью идентичны тем, что определены GNU date и POSIX strftime(3c). Предоставляются дополнительные типы преобразования для доступа к специфичным для Java функциям (например, 'L' для миллисекунд в пределах секунды).

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

END_OF_DOCUMENT_MARKER

time
`'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'`, чтобы принудительно вывести этот результат в верхнем регистре. (Обратите внимание, что `'p'` даёт вывод в нижнем регистре. Это отличается от GNU `date` и POSIX `strftime(3c)`, которые выдают вывод в верхнем регистре.)
`'z'`	`'\u007a'`	Числовой смещение часового пояса от GMT в стиле RFC 822, например, `-0800`. Это значение будет скорректировано при необходимости для перехода на летнее время. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для данной инстанции виртуальной машины Java.
`'Z'`	`'\u005a'`	Строковое представление сокращения часового пояса. Это значение будет скорректировано при необходимости для перехода на летнее время. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для данной инстанции виртуальной машины Java. Локаль форматировщика перебивает локаль аргумента (если таковой имеется).
`'s'`	`'\u0073'`	Строка, представляющая секунды с начала эпохи, начиная с 1 января 1970 `00:00:00` UTC, т.е. `Long.MIN_VALUE/1000` до `Long.MAX_VALUE/1000`.
`'Q'`	`'\u004f'`	Миллисекунды с начала эпохи, начиная с 1 января 1970 `00:00:00` UTC, т.е. `Long.MIN_VALUE` до `Long.MAX_VALUE`. Точность этого значения ограничена разрешением базовой операционной системы или аппаратного обеспечения.

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

date
`'B'`	`'\u0042'`	Полное название месяца в зависимости от локали, например, `"January"`, `"February"`.
`'b'`	`'\u0062'`	Сокращённое название месяца в зависимости от локали, например, `"Jan"`, `"Feb"`.
`'h'`	`'\u0068'`	То же, что и `'b'`.
`'A'`	`'\u0041'`	Полное название дня недели в зависимости от локали, например, `"Sunday"`, `"Monday"`
`'a'`	`'\u0061'`	Сокращённое название дня недели в зависимости от локали, например, `"Sun"`, `"Mon"`
`'C'`	`'\u0043'`	Четырёхзначный год, разделённый на `100`, отформатированный как две цифры с ведущим нулем при необходимости, например, `00 - 99`
`'Y'`	`'\u0059'`	Год, отформатированный как минимум четырьмя цифрами с ведущими нулями при необходимости, например, `0092` равно `92` н.э. для григорианского календаря.
`'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`" — первый день месяца.

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

composites
`'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"`.

Применяется флаг '-' , определённый для общих преобразований. Если задан флаг '#', будет выброшено исключение FormatFlagsConversionMismatchException.

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

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

Процент

Преобразование не соответствует ни одному аргументу.

DTConv
`'%'`	Результатом является буквальный `'%'` (`'\u0025'`) Ширина — это минимальное количество символов, которое должно быть записано в выходной поток, включая `'%'`. Если длина преобразованного значения меньше, чем `width`, то вывод будет дополнен пробелами (`'\u0020'`) до тех пор, пока общее количество символов не станет равным ширине. Дополнение происходит слева. Если ширина не указана, то выводится только `'%'`. Флаг `'-'`, определённый для общих преобразований, применяется. Если указаны другие флаги, то будет выброшено исключение `IllegalFormatFlagsException`. Точность не применима. Если точность указана, будет выброшено исключение `IllegalFormatPrecisionException`.

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

Преобразование не соответствует ни одному аргументу.

DTConv
`'n'`	специфический для платформы разделитель строк, возвращаемый методом `System.lineSeparator()`.

Флаги, ширина и точность не применяются. Если они указаны, будут выброшены исключения IllegalFormatFlagsException, IllegalFormatWidthException и IllegalFormatPrecisionException соответственно.

Индекс аргумента

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

Явное индексирование используется, когда спецификатор формата содержит индекс аргумента. Индекс аргумента — это десятичное целое число, указывающее позицию аргумента в списке аргументов. Первый аргумент обозначается как "1$, второй — как "2$" и т. д. К одному аргументу можно обратиться несколько раз.
Например:
```
   formatter.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"
 
```
Относительное индексирование используется, когда спецификатор формата содержит флаг '<' ('\u003c'), который заставляет повторно использовать аргумент для предыдущего спецификатора формата. Если предыдущего аргумента нет, то вызывается исключение MissingFormatArgumentException.
```
    formatter.format("%s %s %<s %<s", "a", "b", "c", "d")
    // -> "a b b b"
    // "c" and "d" are ignored because they are not referenced
 
```
Обычное индексирование используется, когда спецификатор формата не содержит ни индекса аргумента, ни флага '<'. Каждый спецификатор формата, использующий обычное индексирование, получает последовательный неявный индекс в списке аргументов, который независим от индексов, используемых при явном или относительном индексировании.
```
   formatter.format("%s %s %s %s", "a", "b", "c", "d")
   // -> "a b c d"
 
```

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

   formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
   // -> "b a a b"
   // "c" and "d" are ignored because they are not referenced

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

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

Если не указано иное, передача null аргумента в любой метод или конструктор в этом классе вызовет исключение NullPointerException.

Since:: 1.5

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static enum`	`Formatter.BigDecimalLayoutForm`	Перечисление для форматирования `BigDecimal`.

Краткое описание конструкторов

Конструктор	Описание
`Formatter()`	Создаёт новый форматировщик.
`Formatter(File file)`	Создаёт новый форматировщик с указанным файлом.
`Formatter(File file, String csn)`	Создаёт новый форматировщик с указанным файлом и кодировкой.
`Formatter(File file, String csn, Locale l)`	Создаёт новый форматировщик с указанным файлом, кодировкой и локалью.
`Formatter(File file, Charset charset, Locale l)`	Создаёт новый форматировщик с указанным файлом, кодировкой и локалью.
`Formatter(OutputStream os)`	Создаёт новый форматировщик с указанным потоком вывода.
`Formatter(OutputStream os, String csn)`	Создаёт новый форматировщик с указанным потоком вывода и кодировкой.
`Formatter(OutputStream os, String csn, Locale l)`	Создаёт новый форматировщик с указанным потоком вывода, кодировкой и локалью.
`Formatter(OutputStream os, Charset charset, Locale l)`	Создаёт новый форматировщик с указанным потоком вывода, кодировкой и локалью.
`Formatter(PrintStream ps)`	Создаёт новый форматировщик с указанным потоком печати.
`Formatter(Appendable a)`	Создаёт новый форматировщик с указанным назначением.
`Formatter(Appendable a, Locale l)`	Создаёт новый форматировщик с указанным назначением и локалью.
`Formatter(String fileName)`	Создаёт новый форматировщик с указанным именем файла.
`Formatter(String fileName, String csn)`	Создаёт новый форматировщик с указанным именем файла и кодировкой.
`Formatter(String fileName, String csn, Locale l)`	Создаёт новый форматировщик с указанным именем файла, кодировкой и локалью.
`Formatter(String fileName, Charset charset, Locale l)`	Создаёт новый форматировщик с указанным именем файла, кодировкой и локалью.
`Formatter(Locale l)`	Создаёт новый форматировщик с указанной локалью.

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`close()`	Закрывает этот форматировщик.
`void`	`flush()`	Очищает буфер форматировщика.
`Formatter`	`format(String format, Object... args)`	Записывает отформатированную строку в назначение этого объекта, используя указанную строку формата и аргументы.
`Formatter`	`format(Locale l, String format, Object... args)`	Записывает отформатированную строку в назначение этого объекта, используя указанную локаль, строку формата и аргументы.
`IOException`	`ioException()`	Возвращает `IOException` последнее исключение, выброшенное форматировщиком `Appendable`.
`Locale`	`locale()`	Возвращает локаль, установленную при создании этого форматировщика.
`Appendable`	`out()`	Возвращает назначение для вывода.
`String`	`toString()`	Возвращает результат вызова `toString()` на назначении для вывода.

Методы, унаследованные от класса java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Подробное описание конструкторов

Форматтер

public Formatter()

Создаёт новый форматтер.

Назначение отформатированного вывода — StringBuilder, который можно получить, вызвав out(), и содержимое которого можно преобразовать в строку, вызвав toString(). Используемый язык — по умолчанию для форматирования для данной виртуальной машины Java.

Форматтер

public Formatter(Appendable a)

Создаёт новый форматтер с указанным местом назначения.

Используемый язык — по умолчанию для форматирования для данной виртуальной машины Java.

Параметры:: a - Место назначения отформатированного вывода. Если a равно null, то будет создан StringBuilder.

Форматтер

public Formatter(Locale l)

Создаёт новый форматтер с указанным языком.

Параметры:: l - Язык, применяемый при форматировании. Если l равно null, то локализация не применяется.

Форматтер

public Formatter(Appendable a, Locale l)

Создаёт новый форматтер с указанным местом назначения и языком.

Параметры:: a - Место назначения отформатированного вывода. Если a равно null, то будет создан StringBuilder.; l - Язык, применяемый при форматировании. Если l равно null, то локализация не применяется.

Форматтер

public Formatter(String fileName) throws FileNotFoundException

Создаёт новый форматтер с указанным именем файла.

Используемый набор символов — набор символов по умолчанию для данной виртуальной машины Java.

Используемый язык — по умолчанию для форматирования для данной виртуальной машины Java.

Параметры:: fileName - Имя файла, используемого в качестве места назначения этого форматтера. Если файл существует, он будет обнулен; в противном случае будет создан новый файл. Вывод будет записан в файл с буферизацией.
Исключения:: SecurityException - Если присутствует менеджер безопасности и checkWrite(fileName) отказывается предоставить доступ для записи в файл; FileNotFoundException - Если указанное имя файла не соответствует существующему, доступному для записи обычному файлу и новый обычный файл с таким именем создать невозможно, или при возникновении других ошибок при открытии или создании файла

Форматтер

public Formatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException

Создаёт новый форматтер с указанным именем файла и набором символов.

Используемый язык — по умолчанию для форматирования для данной виртуальной машины Java.

Параметры:: fileName - Имя файла, используемого в качестве места назначения этого форматтера. Если файл существует, он будет обнулен; в противном случае будет создан новый файл. Вывод будет записан в файл с буферизацией.; csn - Имя поддерживаемого набора символов
Исключения:: FileNotFoundException - Если указанное имя файла не соответствует существующему, доступному для записи обычному файлу и новый обычный файл с таким именем создать невозможно, или при возникновении других ошибок при открытии или создании файла; SecurityException - Если присутствует менеджер безопасности и checkWrite(fileName) отказывается предоставить доступ для записи в файл; UnsupportedEncodingException - Если указанный набор символов не поддерживается

Форматтер

public Formatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException

Создаёт новый форматтер с указанным именем файла, набором символов и языком.

Параметры:: fileName - Имя файла, используемого в качестве места назначения этого форматтера. Если файл существует, он будет обнулен; в противном случае будет создан новый файл. Вывод будет записан в файл с буферизацией.; csn - Имя поддерживаемого набора символов; l - Язык, применяемый при форматировании. Если l равно null, то локализация не применяется.
Исключения:: FileNotFoundException - Если указанное имя файла не соответствует существующему, доступному для записи обычному файлу и новый обычный файл с таким именем создать невозможно, или при возникновении других ошибок при открытии или создании файла; SecurityException - Если присутствует менеджер безопасности и checkWrite(fileName) отказывается предоставить доступ для записи в файл; UnsupportedEncodingException - Если указанный набор символов не поддерживается

Форматтер

public Formatter(String fileName, Charset charset, Locale l) throws IOException

Создаёт новый форматтер с указанным именем файла, набором символов и языком.

Параметры:: fileName - Имя файла, используемого в качестве места назначения этого форматтера. Если файл существует, он будет обнулен; в противном случае будет создан новый файл. Вывод будет записан в файл с буферизацией.; charset - набор символов; l - Язык, применяемый при форматировании. Если l равно null, то локализация не применяется.
Исключения:: IOException - если произошла ошибка ввода/вывода при открытии или создании файла; SecurityException - Если присутствует менеджер безопасности и checkWrite(fileName) отказывается предоставить доступ для записи в файл; NullPointerException - если fileName или charset равны null.

Форматтер

public Formatter(File file) throws FileNotFoundException

Создаёт новый форматтер с указанным файлом.

Используемый набор символов — набор символов по умолчанию для данной виртуальной машины Java.

Используемый язык — по умолчанию для форматирования для данной виртуальной машины Java.

Параметры:: file - Файл, используемый в качестве места назначения этого форматтера. Если файл существует, он будет обнулен; в противном случае будет создан новый файл. Вывод будет записан в файл с буферизацией.
Исключения:: SecurityException - Если присутствует менеджер безопасности и checkWrite(file.getPath()) отказывается предоставить доступ для записи в файл; FileNotFoundException - Если указанный объект файла не соответствует существующему, доступному для записи обычному файлу и новый обычный файл с таким именем создать невозможно, или при возникновении других ошибок при открытии или создании файла

Форматтер

public Formatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException

Создаёт новый форматтер с указанным файлом и набором символов.

Используемый язык — по умолчанию для форматирования для данной виртуальной машины Java.

Параметры:: file - Файл, используемый в качестве места назначения этого форматтера. Если файл существует, он будет обнулен; в противном случае будет создан новый файл. Вывод будет записан в файл с буферизацией.; csn - Имя поддерживаемого набора символов
Исключения:: FileNotFoundException - Если указанный объект файла не соответствует существующему, доступному для записи обычному файлу и новый обычный файл с таким именем создать невозможно, или при возникновении других ошибок при открытии или создании файла; SecurityException - Если присутствует менеджер безопасности и checkWrite(file.getPath()) отказывается предоставить доступ для записи в файл; UnsupportedEncodingException - Если указанный набор символов не поддерживается

Форматировщик

public Formatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException

Создаёт новый форматировщик со заданным файлом, кодировкой и локалью.

Параметры:: file - Файл, используемый в качестве назначения для этого форматировщика. Если файл существует, он будет обнулён; в противном случае будет создан новый файл. Вывод будет записан в файл и буферизован.; csn - Имя поддерживаемой кодировки.; l - Локаль, применяемая во время форматирования. Если l равна null, то локализация не применяется.
Исключения:: FileNotFoundException - Если заданный объект файла не обозначает существующий, доступный для записи обычный файл, и новый обычный файл с таким именем не может быть создан, или если произошла какая-либо другая ошибка при открытии или создании файла; SecurityException - Если присутствует менеджер безопасности, и checkWrite(file.getPath()) отказывается предоставить доступ на запись к файлу; UnsupportedEncodingException - Если указанная кодировка не поддерживается

Форматировщик

public Formatter(File file, Charset charset, Locale l) throws IOException

Создаёт новый форматировщик со заданным файлом, кодировкой и локалью.

Параметры:: file - Файл, используемый в качестве назначения для этого форматировщика. Если файл существует, он будет обнулён; в противном случае будет создан новый файл. Вывод будет записан в файл и буферизован.; charset - Кодировка; l - Локаль, применяемая во время форматирования. Если l равна null, то локализация не применяется.
Исключения:: IOException - если произошла ошибка ввода-вывода во время открытия или создания файла; SecurityException - Если присутствует менеджер безопасности, и checkWrite(file.getPath()) отказывается предоставить доступ на запись к файлу; NullPointerException - если file или charset равна null.

Форматировщик

public Formatter(PrintStream ps)

Создаёт новый форматировщик со заданным потоком вывода.

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

Символы записываются в указанный PrintStream объект и, следовательно, закодированы с использованием кодировки этого объекта.

Параметры:: ps - Поток для использования в качестве назначения для этого форматировщика.

Форматировщик

public Formatter(OutputStream os)

Создаёт новый форматировщик со указанным потоком вывода.

Использована по умолчанию кодировка для этого экземпляра виртуальной машины Java.

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

Параметры:: os - Поток вывода для использования в качестве назначения для этого форматировщика. Вывод будет буферизован.

Форматировщик

public Formatter(OutputStream os, String csn) throws UnsupportedEncodingException

Создаёт новый форматировщик со указанным потоком вывода и кодировкой.

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

Параметры:: os - Поток вывода для использования в качестве назначения для этого форматировщика. Вывод будет буферизован.; csn - Имя поддерживаемой кодировки
Исключения:: UnsupportedEncodingException - Если указанная кодировка не поддерживается

Форматировщик

public Formatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException

Создаёт новый форматировщик со указанным потоком вывода, кодировкой и локалью.

Параметры:: os - Поток вывода для использования в качестве назначения для этого форматировщика. Вывод будет буферизован.; csn - Имя поддерживаемой кодировки; l - Локаль, применяемая во время форматирования. Если l равна null, то локализация не применяется.
Исключения:: UnsupportedEncodingException - Если указанная кодировка не поддерживается

Форматировщик

public Formatter(OutputStream os, Charset charset, Locale l)

Создаёт новый форматировщик со указанным потоком вывода, кодировкой и локалью.

Параметры:: os - Поток вывода для использования в качестве назначения для этого форматировщика. Вывод будет буферизован.; charset - Кодировка; l - Локаль, применяемая во время форматирования. Если l равна null, то локализация не применяется.
Исключения:: NullPointerException - если os или charset равна null.

Подробное описание методов

locale

public Locale locale()

Возвращает локаль, установленную при создании этого форматировщика.

Метод format для этого объекта с аргументом locale не изменяет это значение.

Возвращает:: null если локализация не применяется, в противном случае локаль
Исключения:: FormatterClosedException - Если этот форматировщик был закрыт путём вызова его метода close()

out

public Appendable out()

Возвращает назначение для вывода.

Возвращает:: Назначение для вывода
Исключения:: FormatterClosedException - Если этот форматировщик был закрыт путём вызова его метода close()

toString

public String toString()

Возвращает результат вызова toString() для назначения вывода. Например, следующий код форматирует текст в StringBuilder, а затем извлекает результирующую строку:

   Formatter f = new Formatter();
   f.format("Last reboot at %tc", lastRebootDate);
   String s = f.toString();
   // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"

Вызов этого метода ведет себя точно так же, как вызов

     out().toString()

В зависимости от спецификации toString для Appendable, возвращаемая строка может или не может содержать символы, записанные в назначение. Например, буферы обычно возвращают своё содержимое в toString(), но потоки не могут, так как данные отбрасываются.

Overrides:: toString в классе Object
Возвращает:: Результат вызова toString() для назначения вывода
Исключения:: FormatterClosedException - Если этот форматировщик был закрыт путём вызова его метода close()

flush

public void flush()

Очищает этот форматировщик. Если назначение реализует интерфейс Flushable, его метод flush будет вызван.

Очистка форматировщика записывает любой буферизованный вывод в назначении в базовый поток.

Specified by:: flush в интерфейсе Flushable
Исключения:: FormatterClosedException - Если этот форматировщик был закрыт путём вызова его метода close()

close

public void close()

Закрывает этот форматировщик. Если назначение реализует интерфейс Closeable, его метод close будет вызван.

Закрытие форматировщика позволяет освободить ресурсы, которые он может удерживать (например, открытые файлы). Если форматировщик уже закрыт, вызов этого метода не имеет эффекта.

Попытка вызвать любые методы, кроме ioException() в этом форматировщике после его закрытия приведёт к FormatterClosedException.

Specified by:: close в интерфейсе AutoCloseable
Specified by:: close в интерфейсе Closeable

ioException

public IOException ioException()

Возвращает IOException последний выброшенный этим форматировщиком Appendable.

Если метод append() назначения никогда не бросает IOException, то этот метод всегда вернёт null.

Возвращает:: Последнее исключение, выброшенное Appendable, или null если такое исключение не существует.

форматировать

public Formatter format(String format, Object... args)

Записывает отформатированную строку в место назначения этого объекта, используя указанную строку формата и аргументы. Используемый язык определён во время создания этого форматировщика.

Параметры:: format - Строка формата, как описано в Синтаксисе строки формата.; args - Аргументы, на которые ссылаются спецификаторы формата в строке формата. Если аргументов больше, чем спецификаторов формата, лишние аргументы игнорируются. Максимальное количество аргументов ограничено максимальным размером массива Java, определённым в Спецификации виртуальной машины Java.
Возвращает:: Этот форматировщик
Исключения:: IllegalFormatException - Если строка формата содержит неверный синтаксис, спецификатор формата несовместим с заданными аргументами, недостаточно аргументов для заданной строки формата или другие недопустимые условия. Для описания всех возможных ошибок форматирования см. раздел Подробности спецификации класса форматировщика.; FormatterClosedException - Если этот форматировщик был закрыт путём вызова метода close()

форматировать

public Formatter format(Locale l, String format, Object... args)

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

Параметры:: l - Язык языка, применяемый во время форматирования. Если l равен null, то локализация не применяется. Это не изменяет язык этого объекта, установленный во время его создания.; format - Строка формата, как описано в Синтаксисе строки формата; args - Аргументы, на которые ссылаются спецификаторы формата в строке формата. Если аргументов больше, чем спецификаторов формата, лишние аргументы игнорируются. Максимальное количество аргументов ограничено максимальным размером массива Java, определённым в Спецификации виртуальной машины Java.
Возвращает:: Этот форматировщик
Исключения:: IllegalFormatException - Если строка формата содержит неверный синтаксис, спецификатор формата несовместим с заданными аргументами, недостаточно аргументов для заданной строки формата или другие недопустимые условия. Для описания всех возможных ошибок форматирования см. раздел Подробности спецификации класса форматировщика.; FormatterClosedException - Если этот форматировщик был закрыт путём вызова метода close()

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Formatter.html