java.util
接口 Formattable

public interface Formattable

Formattable 接口必须通过需要执行自定义格式化（使用 Formatter 的 's' 转换说明符）的任何类来实现。此接口允许对格式化任意对象的基本控制。 例如，以下类根据标志和长度限制输出股票名称的不同表示形式：

   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。

从以下版本开始：

1.5

方法摘要

void	formatTo(Formatter formatter, int flags, int width, int precision) 使用提供的格式器来格式化对象。

方法详细信息

formatTo

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

使用提供的格式器来格式化对象。

参数：

formatter - 格式器。实现类可以调用 formatter.out() 或 formatter.locale()，以获得分别由此 formatter 使用的 Appendable 或 Locale。

flags - 这些标志将修改输出格式。该值被解释为位掩码(bitmask)。可以将以下标志的组合设置为：FormattableFlags.LEFT_JUSTIFY、FormattableFlags.UPPERCASE 和 FormattableFlags.ALTERNATE。如果没有设置标志，则应用实现类的默认格式。

width - 写入到输出的最少字符数。如果转换值的长度小于 width，那么输出将用 ' ' 来填充，直到总字符数等于 width。默认情况下，从开始处进行填充。如果设置了 FormattableFlags.LEFT_JUSTIFY 标志，则从结尾处进行填充。如果 width 为 -1，则不存在最少字符数。

precision - 写入到输出的最多字符数。precision 应用在 width 之前，因此，即使 width 大于 precision，输出也将被截断为 precision 字符。如果 precision 为 -1，那么对于字符的数量没有明显限制。

抛出：

IllegalFormatException - 如果所有参数都无效。有关所有可能的格式设置错误的规范，请参阅格式器类规范的 Details 一节。