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 一節。