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:

 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 
 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);
           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);
       }
   }
 

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

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

Formattables are not necessarily safe for multithreaded access. Thread safety is optional and may be enforced by 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 formatter argument of the formatTo(java.util.Formatter, int, java.lang.Integer, java.lang.Integer)

Method Summary
void	formatTo formatTo ( Formatter  formatter, int flags, Integer  width, Integer           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

formatTo

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

Formats the object using the provided formatter .

Parameters:

formatter - The formatter . Implementing classes may call formatter.out() or formatter.locale() to obtain the Appendable or Locale used by this formatter respectively.

flags - The flags modify the output format. The value is interpreted as a bitmask. Any combination of the he following flags may be set: FormattableFlags.LEFT_JUSTIFY set LEFT_JUSTIFY , FormattableFlags.UPPERCASE UPPERCASE , and FormattableFlags.ALTERNATE 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 FormattableFlags.LEFT_JUSTIFY LEFT_JUSTIFY flag is set then the padding will be at the end. If width is width null is -1 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 -1 null then there is no explicit limit on the number of characters.

Throws:

IllegalFormatException - If any of the parameters are invalid. For specification of all possible formatting errors, see the Details - 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.