Java java.util 接口 Formattable（JDK5）

所有类

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

formatTo

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

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

参数：

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

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

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

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

抛出：

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