Класс 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
 
```
Необязательный argument_index — это десятичное целое число, указывающее позицию аргумента в списке аргументов. Первый аргумент обозначается "1$", второй — "2$" и т. д.

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

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

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

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

Обязательное преобразование — это последовательность из двух символов. Первый символ — '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. Локаль 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, а также любыми методами-удобствами, такими как 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
Float и Double
BigDecimal

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

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

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

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

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

Byte, Short, Integer и Long

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

IntConv
Преобразование	Unicode	Описание
`'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
Преобразование	Unicode	Описание
`'+'`	`'\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
Преобразование	Unicode	Описание
`'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
Преобразование	Unicode	Описание
`'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
Преобразование	Unicode	Описание
`'t'`	`'\u0074'`	Префикс для символов преобразования даты и времени.
`'T'`	`'\u0054'`	Версия `'t'` с заглавными буквами.

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

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

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

Ширина — минимальное количество символов, которые должны быть записаны в выходной поток. Если длина преобразованного значения меньше 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()`	Возвращает последнее исключение, брошенное форматером в методе `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 - Если указанный кодировщик не поддерживается

END_OF_DOCUMENT_MARKER

Форматтер

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

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

Параметры:: file - Файл, используемый в качестве назначения для этого форматтера. Если файл существует, он будет обнулён; в противном случае будет создан новый файл. Вывод будет записан в файл и буферизован.; csn - Имя поддерживаемой кодировки charset; 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 - Имя поддерживаемой кодировки charset
Исключения:: UnsupportedEncodingException - Если указанная кодировка не поддерживается

Форматтер

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

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

Параметры:: os - Поток вывода, используемый в качестве назначения для этого форматтера. Вывод будет буферизован.; csn - Имя поддерживаемой кодировки charset; 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 для этого объекта с аргументом локали не изменяет это значение.

Возвращает:: 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 если такого исключения не существует.

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

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, 2023, 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/21/docs/api/java.base/java/util/Formatter.html