Класс 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$" и т. д.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

time
Преобразование	Описание
`'H'`	Час суток в 24-часовом формате, выводится двумя цифрами с ведущим нулём при необходимости, например `00 - 23`.
`'I'`	Час в 12-часовом формате, выводится двумя цифрами с ведущим нулём при необходимости, например `01 - 12`.
`'k'`	Час суток в 24-часовом формате, например `0 - 23`.
`'l'`	Час в 12-часовом формате, например `1 - 12`.
`'M'`	Минута в пределах часа, выводится двумя цифрами с ведущим нулём при необходимости, например `00 - 59`.
`'S'`	Секунды в пределах минуты, выводятся двумя цифрами с ведущим нулём при необходимости, например `00 - 60` ("`60`" — специальное значение, необходимое для поддержки високосных секунд).
`'L'`	Миллисекунда в пределах секунды, выводится тремя цифрами с ведущими нулями при необходимости, например `000 - 999`.
`'N'`	Наносекунда в пределах секунды, выводится девятью цифрами с ведущими нулями при необходимости, например `000000000 - 999999999`.
`'p'`	Зависимое от локали обозначение до полудня или после полудня в нижнем регистре, например "`am`" или "`pm`". Использование префикса преобразования `'T'` переводит этот результат в верхний регистр.
`'z'`	Числовое смещение часового пояса относительно GMT в формате RFC 822, например `-0800`. Это значение будет при необходимости скорректировано с учётом перехода на летнее время. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для данного экземпляра виртуальной машины Java.
`'Z'`	Строка, представляющая аббревиатуру часового пояса. Это значение будет при необходимости скорректировано с учётом перехода на летнее время. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для данного экземпляра виртуальной машины Java. Локаль форматтера имеет приоритет над локалью аргумента (если она есть).
`'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.

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

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

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

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

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

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

Общие

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

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

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

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

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

Числовые

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

Byte, Short, Integer и Long
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
Преобразование	Unicode	Описание
`'d'`	`'\u0064'`	Требует форматировать результат как десятичное целое число. Применяется алгоритм локализации. Если указан флаг `'#'`, будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'o'`	`'\u006f'`	Требует форматировать результат как целое число в восьмеричной системе счисления. Локализация не выполняется. Если x отрицательно, результатом будет знаковое значение, начинающееся с `'-'` (`'\u002d'`). Для этого типа допускается знаковый вывод, поскольку, в отличие от примитивных типов, невозможно создать эквивалентное беззнаковое значение, не предполагая явно размер типа данных. Если x положительно или равно нулю и указан флаг `'+'`, результат будет начинаться с `'+'` (`'\u002b'`). Если указан флаг `'#'`, результат всегда будет начинаться с префикса `'0'`. Если указан флаг `'0'`, результат будет дополнен ведущими нулями до ширины поля после любого знака. Если указан флаг `','`, будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'x'`	`'\u0078'`	Требует форматировать результат как целое число в шестнадцатеричной системе счисления. Локализация не выполняется. Если x отрицательно, результатом будет знаковое значение, начинающееся с `'-'` (`'\u002d'`). Для этого типа допускается знаковый вывод, поскольку, в отличие от примитивных типов, невозможно создать эквивалентное беззнаковое значение, не предполагая явно размер типа данных. Если x положительно или равно нулю и указан флаг `'+'`, результат будет начинаться с `'+'` (`'\u002b'`). Если указан флаг `'#'`, результат всегда будет начинаться с индикатора системы счисления `"0x"`. Если указан флаг `'0'`, результат будет дополнен ведущими нулями до ширины поля после индикатора системы счисления или знака (если он есть). Если указан флаг `','`, будет выброшено исключение `FormatFlagsConversionMismatchException`.
`'X'`	`'\u0058'`	Вариант `'x'` в верхнем регистре. Вся строка, представляющая число, переводится в верхний регистр, включая `'x'` (если есть) и все шестнадцатеричные цифры `'a'` – `'f'` (`'\u0061'` – `'\u0066'`).

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

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

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

Правила задания ширины такие же, как для типов Byte, Short, Integer и Long.

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

Float и Double

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

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

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

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

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

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

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

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

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

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

BigDecimal

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

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

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

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

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

Правила задания ширины и точности совпадают с определёнными для Float и Double.

Дата/время

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

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

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

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

time
Преобразование	Юникод	Описание
`'H'`	`'\u0048'`	Час суток в 24-часовом формате, представленный двумя цифрами с ведущим нулём при необходимости, например `00 - 23`. `00` соответствует полуночи.
`'I'`	`'\u0049'`	Час в 12-часовом формате, представленный двумя цифрами с ведущим нулём при необходимости, например `01 - 12`. `01` соответствует часу дня (утра или вечера).
`'k'`	`'\u006b'`	Час суток в 24-часовом формате, например `0 - 23`. `0` соответствует полуночи.
`'l'`	`'\u006c'`	Час в 12-часовом формате, например `1 - 12`. `1` соответствует часу дня (утра или вечера).
`'M'`	`'\u004d'`	Минута в пределах часа, представленная двумя цифрами с ведущим нулём при необходимости, например `00 - 59`.
`'S'`	`'\u0053'`	Секунды в пределах минуты, представленные двумя цифрами с ведущим нулём при необходимости, например `00 - 60` ("`60`" — специальное значение, необходимое для поддержки високосных секунд).
`'L'`	`'\u004c'`	Миллисекунда в пределах секунды, представленная тремя цифрами с ведущими нулями при необходимости, например `000 - 999`.
`'N'`	`'\u004e'`	Наносекунда в пределах секунды, представленная девятью цифрами с ведущими нулями при необходимости, например `000000000 - 999999999`. Точность этого значения ограничена разрешением используемой операционной системы или аппаратного обеспечения.
`'p'`	`'\u0070'`	Зависящий от локали маркер утра или вечера в нижнем регистре, например "`am`" или "`pm`". Использование префикса преобразования `'T'` переводит этот результат в верхний регистр. (Обратите внимание, что `'p'` формирует результат в нижнем регистре. Это отличается от GNU `date` и POSIX `strftime(3c)`, которые формируют результат в верхнем регистре.)
`'z'`	`'\u007a'`	Числовое смещение часового пояса от GMT в формате RFC 822, например `-0800`. Это значение при необходимости корректируется с учётом летнего времени. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для данного экземпляра виртуальной машины Java.
`'Z'`	`'\u005a'`	Строка, представляющая аббревиатуру часового пояса. Это значение при необходимости корректируется с учётом летнего времени. Для `long`, `Long` и `Date` используется часовой пояс по умолчанию для данного экземпляра виртуальной машины Java. Локаль форматировщика имеет приоритет над локалью аргумента (если она задана).
`'s'`	`'\u0073'`	Количество секунд с начала эпохи, начавшейся 1 января 1970 года `00:00:00` UTC, то есть от `Long.MIN_VALUE/1000` до `Long.MAX_VALUE/1000`.
`'Q'`	`'\u004f'`	Количество миллисекунд с начала эпохи, начавшейся 1 января 1970 года `00:00:00` UTC, то есть от `Long.MIN_VALUE` до `Long.MAX_VALUE`. Точность этого значения ограничена разрешением используемой операционной системы или аппаратного обеспечения.

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

date
Преобразование	Юникод	Описание
`'B'`	`'\u0042'`	Зависящее от локали полное название месяца, например `"January"`, `"February"`.
`'b'`	`'\u0062'`	Зависящее от локали сокращённое название месяца, например `"Jan"`, `"Feb"`.
`'h'`	`'\u0068'`	То же, что и `'b'`.
`'A'`	`'\u0041'`	Зависящее от локали полное название дня недели, например `"Sunday"`, `"Monday"`
`'a'`	`'\u0061'`	Зависящее от локали сокращённое название дня недели, например `"Sun"`, `"Mon"`
`'C'`	`'\u0043'`	Четырёхзначный год, делённый на `100`, представленный двумя цифрами с ведущим нулём при необходимости, например `00 - 99`
`'Y'`	`'\u0059'`	Год, представленный как минимум четырьмя цифрами с ведущими нулями при необходимости; например, `0092` соответствует `92` году н. э. в григорианском календаре.
`'y'`	`'\u0079'`	Последние две цифры года с ведущими нулями при необходимости, например `00 - 99`.
`'j'`	`'\u006a'`	День года, представленный тремя цифрами с ведущими нулями при необходимости, например `001 - 366` для григорианского календаря. `001` соответствует первому дню года.
`'m'`	`'\u006d'`	Месяц, представленный двумя цифрами с ведущими нулями при необходимости, например `01 - 13`, где "`01`" — первый месяц года, а "`13`" — специальное значение, необходимое для поддержки лунных календарей.
`'d'`	`'\u0064'`	День месяца, представленный двумя цифрами с ведущими нулями при необходимости, например `01 - 31`, где "`01`" — первый день месяца.
`'e'`	`'\u0065'`	День месяца, представленный двумя цифрами, например `1 - 31`, где "`1`" — первый день месяца.

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

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

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

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

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

Знак процента

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Начиная с версии:

1.5

Внешние спецификации

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

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

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

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

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

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

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

Formatter

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

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

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

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

Formatter

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

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

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

Formatter

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

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

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

Formatter

public Formatter(File file) throws FileNotFoundException

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

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

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

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

Formatter

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

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

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

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

Formatter

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

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

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

Formatter

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

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

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

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 — Если указанная кодировка не поддерживается

Formatter

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

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

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

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

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, если такого исключения нет.

format

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

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

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

format

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

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

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

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