java.util
Interface Formattable

public interface Formattable

The Formattable interface must be implemented by any class that needs to perform custom formatting using the 's' conversion specifier of Formatter. This interface allows basic control for formatting arbitrary objects. For example, the following class prints out different representations of a stock's name depending on the flags and length constraints: 

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

       ...

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

           // apply precision
           if (precision == null) {
               // no maximum width
               sb.append(companyName);
           } else if (precision < 10 || 
                        (f & Formattable.ALTERNATE == Formattable.ALTERNATE)) {
               sb.append(symbol.substring(0, Math.min(symbol.length(), precision)));
           } else if (companyName.length() < precision) {
               sb.append(companyName);
           } else {
              sb.append(companyName.substring(0, precision - 1)).append('*');
           }

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

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

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

When used in conjunction with the Formatter, the above class produces the following output for various format strings. 

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

Formattables are not necessarily safe for multithreaded access. Thread safety is the responsibility of classes that extend and implement this interface.

Unless otherwise specified, passing a null argument to any method in this interface will cause a NullPointerException to be thrown.

Since:
1.5

Field Summary
static int ALTERNATE
          Requires the output to use an alternate form.
static int LEFT_JUSTIFY
          Left-justifies the output.
static int UPPERCASE
          Converts the output to upper case according to the rules of the locale given during creation of the formatter argument of the formatTo(java.util.Formatter, int, java.lang.Integer, java.lang.Integer) method.
 
Method Summary
 void formatTo(Formatter formatter, int flags, Integer width, Integer precision)
          Formats the object using the provided formatter.
 

Field Detail

LEFT_JUSTIFY

static final int LEFT_JUSTIFY
Left-justifies the output. Spaces ('\u0020') will be added at the end of the converted value as required to fill the minimum width of the field. If this flag is not set then the output will be right-justified.

This flag corresponds to '-' ('\u002d') in the format specifier.

See Also:
Constant Field Values

UPPERCASE

static final int UPPERCASE
Converts the output to upper case according to the rules of the locale given during creation of the formatter argument of the formatTo(java.util.Formatter, int, java.lang.Integer, java.lang.Integer) method. The output should be equivalent the following invocation of String.toUpperCase(java.util.Locale) 
     out.toUpperCase()

This flag corresponds to '^' ('\u005e') in the format specifier.

See Also:
Constant Field Values

ALTERNATE

static final int ALTERNATE
Requires the output to use an alternate form. The definition of the form is specified by the Formattable.

This flag corresponds to '#' ('\u0023') in the format specifier.

See Also:
Constant Field Values
Method Detail

formatTo

void formatTo(Formatter formatter,
              int flags,
              Integer width,
              Integer precision)
Formats the object using the provided formatter.

Parameters:
formatter - The formatter
flags - The flags modify the output format. The value is interpreted as a bitmask. Any combination of he following flags may be set LEFT_JUSTIFY, UPPERCASE, and ALTERNATE. If no flags are set, the default formatting of the implementing class will apply.
width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by '  ' until the total number of characters equals width. The padding is at the beginning by default. If the LEFT_JUSTIFY flag is set then the padding will be at the end. If width is null then there is no minimum.
precision - The maximum number of characters to be written to the output. The precision is applied before the width, thus the output will be truncated to precision characters even if the width is greater than the precision. If precision is null then there is no explicit limit on the number of characters.
Throws:
IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.