1 /* 2 * @(#)Formattable.java 1.3 04/04/21 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.util; 9 10 import java.io.IOException; 11 12 /** 13 * The <tt>Formattable</tt> interface must be implemented by any class that 14 * needs to perform custom formatting using the <tt>'s'</tt> conversion 15 * specifier of {@link java.util.Formatter}. This interface allows basic 16 * control for formatting arbitrary objects. 17 * 18 * For example, the following class prints out different representations of a 19 * stock's name depending on the flags and length constraints: 20 * 21 * <blockquote><pre> 22 * import java.nio.CharBuffer; 23 * import java.util.Formatter; 24 * import java.util.Formattable; 25 * import java.util.Locale; 26 * import static java.util.FormattableFlags.*; 27 * 28 * ... 29 * 30 * public class StockName implements Formattable { 31 * private String symbol, companyName, frenchCompanyName; 32 * public StockName(String symbol, String companyName, 33 * String frenchCompanyName) { 34 * ... 35 * } 36 * 37 * ... 38 * 39 * public void formatTo(Formatter fmt, int f, int width, int precision) { 40 * StringBuilder sb = new StringBuilder(); 41 * 42 * // decide form of name 43 * String name = companyName; 44 * if (fmt.locale().equals(Locale.FRANCE)) 45 * name = frenchCompanyName; 46 * boolean alternate = (f & ALTERNATE) == ALTERNATE; 47 * boolean usesymbol = alternate || (precision != -1 && precision < 10); 48 * String out = (usesymbol ? symbol : name); 49 * 50 * // apply precision 51 * if (precision == -1 || out.length() < precision) { 52 * // write it all 53 * sb.append(out); 54 * } else { 55 * sb.append(out.substring(0, precision - 1)).append('*'); 56 * } 57 * 58 * // apply width and justification 59 * int len = sb.length(); 60 * if (len < width) 61 * for (int i = 0; i < width - len; i++) 62 * if ((f & LEFT_JUSTIFY) == LEFT_JUSTIFY) 63 * sb.append(' '); 64 * else 65 * sb.insert(0, ' '); 66 * 67 * fmt.format(sb.toString()); 68 * } 69 * 70 * public String toString() { 71 * return String.format("%s - %s", symbol, companyName); 72 * } 73 * } 74 * </pre></blockquote> 75 * 76 * <p> When used in conjunction with the {@link java.util.Formatter}, the above 77 * class produces the following output for various format strings. 78 * 79 * <blockquote><pre> 80 * Formatter fmt = new Formatter(); 81 * StockName sn = new StockName("HUGE", "Huge Fruit, Inc.", 82 * "Fruit Titanesque, Inc."); 83 * fmt.format("%s", sn); // -> "Huge Fruit, Inc." 84 * fmt.format("%s", sn.toString()); // -> "HUGE - Huge Fruit, Inc." 85 * fmt.format("%#s", sn); // -> "HUGE" 86 * fmt.format("%-10.8s", sn); // -> "HUGE " 87 * fmt.format("%.12s", sn); // -> "Huge Fruit,*" 88 * fmt.format(Locale.FRANCE, "%25s", sn); // -> " Fruit Titanesque, Inc." 89 * </pre></blockquote> 90 * 91 * <p> Formattables are not necessarily safe for multithreaded access. Thread 92 * safety is optional and may be enforced by classes that extend and implement 93 * this interface. 94 * 95 * <p> Unless otherwise specified, passing a <tt>null</tt> argument to 96 * any method in this interface will cause a {@link 97 * NullPointerException} to be thrown. 98 * 99 * @version 1.3, 04/21/04 100 * @since 1.5 101 */ 102 public interface Formattable { 103 104 /** 105 * Formats the object using the provided {@link Formatter formatter}. 106 * 107 * @param formatter 108 * The {@link Formatter formatter}. Implementing classes may call 109 * {@link Formatter#out() formatter.out()} or {@link 110 * Formatter#locale() formatter.locale()} to obtain the {@link 111 * Appendable} or {@link Locale} used by this 112 * <tt>formatter</tt> respectively. 113 * 114 * @param flags 115 * The flags modify the output format. The value is interpreted as 116 * a bitmask. Any combination of the following flags may be set: 117 * {@link FormattableFlags#LEFT_JUSTIFY}, {@link 118 * FormattableFlags#UPPERCASE}, and {@link 119 * FormattableFlags#ALTERNATE}. If no flags are set, the default 120 * formatting of the implementing class will apply. 121 * 122 * @param width 123 * The minimum number of characters to be written to the output. 124 * If the length of the converted value is less than the 125 * <tt>width</tt> then the output will be padded by 126 * <tt>' '</tt> until the total number of characters 127 * equals width. The padding is at the beginning by default. If 128 * the {@link FormattableFlags#LEFT_JUSTIFY} flag is set then the 129 * padding will be at the end. If <tt>width</tt> is <tt>-1</tt> 130 * then there is no minimum. 131 * 132 * @param precision 133 * The maximum number of characters to be written to the output. 134 * The precision is applied before the width, thus the output will 135 * be truncated to <tt>precision</tt> characters even if the 136 * <tt>width</tt> is greater than the <tt>precision</tt>. If 137 * <tt>precision</tt> is <tt>-1</tt> then there is no explicit 138 * limit on the number of characters. 139 * 140 * @throws IllegalFormatException 141 * If any of the parameters are invalid. For specification of all 142 * possible formatting errors, see the <a 143 * HREF="../util/Formatter.html#detail">Details</a> section of the 144 * formatter class specification. 145 */ 146 void formatTo(Formatter formatter, int flags, int width, int precision); 147 } 148