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