Класс Formatter

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"

Как в 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

  Необязательные флаги и ширина определены как указано выше.

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

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

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