Интерфейс Formattable

public interface Formattable

Интерфейс Formattable должен быть реализован любым классом, который нуждается в выполнении пользовательской форматирования с использованием спецификатора преобразования 's' Formatter. Этот интерфейс позволяет осуществлять базовый контроль форматирования произвольных объектов. Например, следующий класс выводит различные представления имени ценной бумаги в зависимости от флагов и ограничений длины:

import java.nio.CharBuffer;
   import java.util.Formatter;
   import java.util.Formattable;
   import java.util.Locale;
   import static java.util.FormattableFlags.*;

   ...

   public class StockName implements Formattable {
       private String symbol, companyName, frenchCompanyName;
       public StockName(String symbol, String companyName,
                        String frenchCompanyName) {
           ...
       }

       ...

       public void formatTo(Formatter fmt, int f, int width, int precision) {
           StringBuilder sb = new StringBuilder();

           // decide form of name
           String name = companyName;
           if (fmt.locale().equals(Locale.FRANCE))
               name = frenchCompanyName;
           boolean alternate = (f & ALTERNATE) == ALTERNATE;
           boolean usesymbol = alternate || (precision != -1 && precision < 10);
           String out = (usesymbol ? symbol : name);

           // apply precision
           if (precision == -1 || out.length() < precision) {
               // write it all
               sb.append(out);
           } else {
               sb.append(out.substring(0, precision - 1)).append('*');
           }

           // apply width and justification
           int len = sb.length();
           if (len < width)
               for (int i = 0; i < width - len; i++)
                   if ((f & LEFT_JUSTIFY) == LEFT_JUSTIFY)
                       sb.append(' ');
                   else
                       sb.insert(0, ' ');

           fmt.format(sb.toString());
       }

       public String toString() {
           return String.format("%s - %s", symbol, companyName);
       }
   }

При использовании совместно с Formatter, вышеупомянутый класс выводит следующий вывод для различных строк форматирования.

Formatter fmt = new Formatter();
   StockName sn = new StockName("HUGE", "Huge Fruit, Inc.",
                                "Fruit Titanesque, Inc.");
   fmt.format("%s", sn);                   //   -> "Huge Fruit, Inc."
   fmt.format("%s", sn.toString());        //   -> "HUGE - Huge Fruit, Inc."
   fmt.format("%#s", sn);                  //   -> "HUGE"
   fmt.format("%-10.8s", sn);              //   -> "HUGE      "
   fmt.format("%.12s", sn);                //   -> "Huge Fruit,*"
   fmt.format(Locale.FRANCE, "%25s", sn);  //   -> "   Fruit Titanesque, Inc."

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

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

Методы

formatTo

void formatTo(Formatter formatter,
              int flags,
              int width,
              int precision)

Форматирует объект с помощью предоставленного formatter.

Параметры:

formatter - Объект formatter. Реализующие классы могут вызывать formatter.out() или formatter.locale() для получения Appendable или Locale, используемых этим formatter соответственно.

flags - Флаги изменяют формат вывода. Значение интерпретируется как битовая маска. Любое сочетание следующих флагов может быть установлено: FormattableFlags.LEFT_JUSTIFY, FormattableFlags.UPPERCASE и FormattableFlags.ALTERNATE. Если флаги не установлены, применяется по умолчанию форматирование реализующего класса.

width - Минимальное количество символов, которые должны быть записаны в выходной поток. Если длина преобразованного значения меньше, чем width, то вывод будет заполнен ' ', пока общее количество символов не достигнет ширины. По умолчанию заполнение происходит в начале. Если установлен флаг FormattableFlags.LEFT_JUSTIFY, то заполнение будет происходить в конце. Если width равно -1, то минимальной длины нет.

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

Исключения:

IllegalFormatException - Если любой из параметров является недопустимым. Для спецификации всех возможных ошибок форматирования см. раздел «Детали» спецификации класса formatter.