Класс 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')
Разделитель строки — производит платформенно-зависимый разделитель строки

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

out.toUpperCase()

Преобразование	Категория аргумента	Описание
`'b'`, `'B'`	общее	Если аргумент arg равен `null`, то результат — "`false`". Если arg — это `boolean` или `Boolean`, то результат — строка, возвращаемая `String.valueOf(arg)`. В противном случае результат — "true".
`'h'`, `'H'`	общее	Если аргумент arg равен `null`, то результат — "`null`". В противном случае результат получается путём вызова `Integer.toHexString(arg.hashCode())`.
`'s'`, `'S'`	общее	Если аргумент arg равен `null`, то результат — "`null`". Если 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' для миллисекунд в секунде).

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

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

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

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

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

`'R'`	Время в 24-часовом формате как `"%tH:%tM"`
`'T'`	Время в 24-часовом формате как `"%tH:%tM:%tS"`.
`'r'`	Время в 12-часовом формате как `"%tI:%tM:%tS %Tp"`. Позиция маркера утра/дня (`'%Tp'`) может зависеть от локали.
`'D'`	Дата, отформатированная как `"%tm/%td/%ty"`.
`'F'`	Полная дата в формате ISO 8601, отформатированная как `"%tY-%tm-%td"`.
`'c'`	Дата и время, отформатированные как `"%ta %tb %td %tT %tZ %tY"`, например, `"Sun Jul 20 16:17:00 EDT 1969"`.

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

Флаги

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

Флаг	Общий	Символ	Целое	Вещественное	Дата/Время	Описание
'-'	y	y	y	y	y	Результат будет выровнен по левому краю.
'#'	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.

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

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

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

out.toUpperCase()

Общие преобразования

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

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

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

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

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

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

Символ

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

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

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

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

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

Числовые

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

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

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

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

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

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

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

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

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

`'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" для шестнадцатеричной системы), определённое количество нулей (в зависимости от ширины) и значение.

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

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

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

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

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

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

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

BigInteger

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

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

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

`'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

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

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

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

`'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. Локаль Formatter перебивает локаль аргумента (если есть).
`'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`. Точность этого значения ограничена разрешением базовой операционной системы или оборудования.

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

`'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`" — первый день месяца.

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

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

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

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

Процент

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

'%'

Результат — буквальный символ '%' ('\u0025').

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

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

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

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

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

'n' Разделитель строк, специфичный для платформы, возвращаемый методом System.getProperty("line.separator").

Флаги, ширина и точность не применяются. Если они указаны, будут выброшены исключения 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 class`	`Formatter.BigDecimalLayoutForm` Перечисление для форматирования `BigDecimal`.

Конструкторы

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

Методы

Модификатор и тип	Метод и описание
`void`	`close()` Закрывает этот форматировщик.
`void`	`flush()` Очищает этот форматировщик.
`Formatter`	`format(Locale l, String format, Object... args)` Записывает отформатированную строку в место назначения этого объекта с использованием указанного локали, строки форматирования и аргументов.
`Formatter`	`format(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

Конструкторы

Formatter

public Formatter()

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

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

Formatter

public Formatter(Appendable a)

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

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

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

Formatter

public Formatter(Locale l)

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

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

Formatter

public Formatter(Appendable a,
                 Locale l)

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

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

Formatter

public Formatter(String fileName)
          throws FileNotFoundException

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

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

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

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

Formatter

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

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

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

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

Formatter

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

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

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

Formatter

public Formatter(File file)
          throws FileNotFoundException

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

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

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

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

Formatter

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

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

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

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

Formatter

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

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

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

Formatter

public Formatter(PrintStream ps)

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

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

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

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

Formatter

public Formatter(OutputStream os)

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

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

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

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

Formatter

public Formatter(OutputStream os,
                 String csn)
          throws UnsupportedEncodingException

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

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

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

Formatter

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

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

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

Методы

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 в интерфейсе Closeable
Указано в:: close в интерфейсе AutoCloseable

ioException

public IOException ioException()

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

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

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

format

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

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

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

format

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

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

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

© 1993, 2020, 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.