Интерфейс 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.