Класс 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'`	символ	Результатом является символ Юникода
`'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. Локаль форматировщика перебивает локаль аргумента (если таковая имеется).
`'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);

Подробности

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

END_OF_DOCUMENT_MARKER

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

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

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

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

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

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

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

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

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

Общее

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

dgConv
Преобразование	Unicode	Описание
`'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
Флаг	Unicode	Описание
`'-'`	`'\u002d'`	Выравнивание вывода влево. Пробелы (`'\u0020'`) добавляются в конец преобразованного значения по мере необходимости, чтобы заполнить минимальную ширину поля. Если ширина не указана, будет выброшено исключение `MissingFormatWidthException`. Если флаг не указан, вывод выравнивается вправо.
`'#'`	`'\u0023'`	Требуется использование альтернативной формы вывода. Определение формы задаётся преобразованием.

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

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

Символ

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

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

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

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

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

Числовое

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

Байт, Краткое, Целое и Длинное
BigInteger
Числа с плавающей точкой и Double
BigDecimal

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

BigInteger

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

bIntConv
Преобразование	Unicode	Описание
`'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'`	Требует, чтобы вывод был отформатирован с использованием компьютерной научной нотации. Применяется алгоритм локализации. Аргумент типа `float` или `Float` сначала преобразуется в `double` или `Double` без потери точности. Форматирование величины 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`. Если точность меньше количества цифр, которые появляются после десятичной точки в строке, возвращаемой методом `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'`	Требует, чтобы вывод был отформатирован с использованием десятичного формата. Применяется алгоритм локализации. Аргумент типа `float` или `Float` сначала преобразуется в `double` или `Double` без потери точности. Результат представляет собой строку, представляющую знак и величину (абсолютное значение) аргумента. Форматирование знака описано в алгоритме локализации. Форматирование величины m зависит от её значения. Если m равно NaN или бесконечности, то выводятся строковые литералы "NaN" или "Infinity" соответственно. Эти значения не локализуются. Величина форматируется как целая часть m без ведущих нулей, за которой следует десятичная запятая, за которой следуют одна или несколько десятичных цифр, представляющие дробную часть m. Количество цифр в результате для дробной части m или a равно точности. Если точность не указана, то значение по умолчанию равно `6`. Если точность меньше количества цифр, которые появляются после десятичной точки в строке, возвращаемой методом `Double.toString(double)`, то значение будет округлено с использованием алгоритма округления до ближайшего целого. В противном случае нули могут быть добавлены для достижения точности. Для канонического представления значения используйте `Float.toString(float)` или `Double.toString(double)` соответственно.
`'a'`	`'\u0061'`	Требует вывода в шестнадцатеричном экспоненциальном формате. Локализация не применяется. Результат представляет собой строку, представляющую знак и величину (абсолютное значение) аргумента x. Если x отрицательное или отрицательный ноль, то результат начнётся со строки `'-'` (`'\u002d'`). Если x положительное или положительный ноль и указан флаг `'+'`, то результат начнётся со строки `'+'` (`'\u002b'`). Форматирование величины m зависит от её значения. Если значение равно NaN или бесконечности, то выводятся строковые литералы "NaN" или "Infinity" соответственно. Если m равно нулю, то оно представляется строкой `"0x0.0p0"`. Если m — нормализованное значение с нормализованным представлением, то для представления значащей части и поля показателя степени используются подстроки. Значащая часть представляется символами `"0x1."`, за которыми следует шестнадцатеричное представление остальной части значащей части как дроби. Показатель степени представляется символами `'p'` (`'\u0070'`), за которыми следует десятичная строка смещённого показателя степени, как если бы она была получена вызовом `Integer.toString` для значения показателя степени. Если точность указана, значение округляется до заданного количества шестнадцатеричных цифр. Если m — значение с поднормализованным представлением, то, если точность не указана в диапазоне от 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'`	Численное смещение часового пояса относительно Гринвича в формате 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` 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`" — первый день месяца.

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

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. Если индекс аргумента не соответствует имеющемуся аргументу, выбрасывается исключение

   formatter.format("%s %s %s %s", "a", "b", "c", "d")
   // -> "a b c d"

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

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

Since:

1.5

External Specifications

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

Modifier and Type	Class	Description
`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)`	Создаёт новый форматировщик с указанным языковым стандартом.

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

Modifier and Type	Метод	Описание
`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 — Имя файла, используемого в качестве пункта назначения этого форматировщика. Если файл существует, он будет обнулён; в противном случае будет создан новый файл. Вывод будет записан в файл и буферизован.
Исключения:: FileNotFoundException — Если заданное имя файла не соответствует существующему, записываемому обычному файлу и новый обычный файл с таким именем создать нельзя, или при возникновении других ошибок при открытии или создании файла

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

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

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

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

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

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

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

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

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

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

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

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

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

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

public Formatter(File file) throws FileNotFoundException

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

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

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

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

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

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

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

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

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

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

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

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

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

Форматтер

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

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

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

Форматтер

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.
С:: 10

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

локаль

public Locale locale()

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

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

Возвращает:: 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(), но потоки не могут, так как данные отбрасываются.

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

flush

public void flush()

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

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

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

close

public void close()

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

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

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

Определяет:: close в интерфейсе AutoCloseable
Определяет:: close в интерфейсе Closeable

ioException

public IOException ioException()

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

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

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

format

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

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

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

format

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

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

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

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/Formatter.html