39 package java.text; |
39 package java.text; |
40 |
40 |
41 import java.io.Serializable; |
41 import java.io.Serializable; |
42 |
42 |
43 /** |
43 /** |
44 * <code>Format</code> is an abstract base class for formatting locale-sensitive |
44 * {@code Format} is an abstract base class for formatting locale-sensitive |
45 * information such as dates, messages, and numbers. |
45 * information such as dates, messages, and numbers. |
46 * |
46 * |
47 * <p> |
47 * <p> |
48 * <code>Format</code> defines the programming interface for formatting |
48 * {@code Format} defines the programming interface for formatting |
49 * locale-sensitive objects into <code>String</code>s (the |
49 * locale-sensitive objects into {@code String}s (the |
50 * <code>format</code> method) and for parsing <code>String</code>s back |
50 * {@code format} method) and for parsing {@code String}s back |
51 * into objects (the <code>parseObject</code> method). |
51 * into objects (the {@code parseObject} method). |
52 * |
52 * |
53 * <p> |
53 * <p> |
54 * Generally, a format's <code>parseObject</code> method must be able to parse |
54 * Generally, a format's {@code parseObject} method must be able to parse |
55 * any string formatted by its <code>format</code> method. However, there may |
55 * any string formatted by its {@code format} method. However, there may |
56 * be exceptional cases where this is not possible. For example, a |
56 * be exceptional cases where this is not possible. For example, a |
57 * <code>format</code> method might create two adjacent integer numbers with |
57 * {@code format} method might create two adjacent integer numbers with |
58 * no separator in between, and in this case the <code>parseObject</code> could |
58 * no separator in between, and in this case the {@code parseObject} could |
59 * not tell which digits belong to which number. |
59 * not tell which digits belong to which number. |
60 * |
60 * |
61 * <h2>Subclassing</h2> |
61 * <h2>Subclassing</h2> |
62 * |
62 * |
63 * <p> |
63 * <p> |
64 * The Java Platform provides three specialized subclasses of <code>Format</code>-- |
64 * The Java Platform provides three specialized subclasses of {@code Format}-- |
65 * <code>DateFormat</code>, <code>MessageFormat</code>, and |
65 * {@code DateFormat}, {@code MessageFormat}, and |
66 * <code>NumberFormat</code>--for formatting dates, messages, and numbers, |
66 * {@code NumberFormat}--for formatting dates, messages, and numbers, |
67 * respectively. |
67 * respectively. |
68 * <p> |
68 * <p> |
69 * Concrete subclasses must implement three methods: |
69 * Concrete subclasses must implement three methods: |
70 * <ol> |
70 * <ol> |
71 * <li> <code>format(Object obj, StringBuffer toAppendTo, FieldPosition pos)</code> |
71 * <li> {@code format(Object obj, StringBuffer toAppendTo, FieldPosition pos)} |
72 * <li> <code>formatToCharacterIterator(Object obj)</code> |
72 * <li> {@code formatToCharacterIterator(Object obj)} |
73 * <li> <code>parseObject(String source, ParsePosition pos)</code> |
73 * <li> {@code parseObject(String source, ParsePosition pos)} |
74 * </ol> |
74 * </ol> |
75 * These general methods allow polymorphic parsing and formatting of objects |
75 * These general methods allow polymorphic parsing and formatting of objects |
76 * and are used, for example, by <code>MessageFormat</code>. |
76 * and are used, for example, by {@code MessageFormat}. |
77 * Subclasses often also provide additional <code>format</code> methods for |
77 * Subclasses often also provide additional {@code format} methods for |
78 * specific input types as well as <code>parse</code> methods for specific |
78 * specific input types as well as {@code parse} methods for specific |
79 * result types. Any <code>parse</code> method that does not take a |
79 * result types. Any {@code parse} method that does not take a |
80 * <code>ParsePosition</code> argument should throw <code>ParseException</code> |
80 * {@code ParsePosition} argument should throw {@code ParseException} |
81 * when no text in the required format is at the beginning of the input text. |
81 * when no text in the required format is at the beginning of the input text. |
82 * |
82 * |
83 * <p> |
83 * <p> |
84 * Most subclasses will also implement the following factory methods: |
84 * Most subclasses will also implement the following factory methods: |
85 * <ol> |
85 * <ol> |
86 * <li> |
86 * <li> |
87 * <code>getInstance</code> for getting a useful format object appropriate |
87 * {@code getInstance} for getting a useful format object appropriate |
88 * for the current locale |
88 * for the current locale |
89 * <li> |
89 * <li> |
90 * <code>getInstance(Locale)</code> for getting a useful format |
90 * {@code getInstance(Locale)} for getting a useful format |
91 * object appropriate for the specified locale |
91 * object appropriate for the specified locale |
92 * </ol> |
92 * </ol> |
93 * In addition, some subclasses may also implement other |
93 * In addition, some subclasses may also implement other |
94 * <code>getXxxxInstance</code> methods for more specialized control. For |
94 * {@code getXxxxInstance} methods for more specialized control. For |
95 * example, the <code>NumberFormat</code> class provides |
95 * example, the {@code NumberFormat} class provides |
96 * <code>getPercentInstance</code> and <code>getCurrencyInstance</code> |
96 * {@code getPercentInstance} and {@code getCurrencyInstance} |
97 * methods for getting specialized number formatters. |
97 * methods for getting specialized number formatters. |
98 * |
98 * |
99 * <p> |
99 * <p> |
100 * Subclasses of <code>Format</code> that allow programmers to create objects |
100 * Subclasses of {@code Format} that allow programmers to create objects |
101 * for locales (with <code>getInstance(Locale)</code> for example) |
101 * for locales (with {@code getInstance(Locale)} for example) |
102 * must also implement the following class method: |
102 * must also implement the following class method: |
103 * <blockquote> |
103 * <blockquote> |
104 * <pre> |
104 * <pre> |
105 * public static Locale[] getAvailableLocales() |
105 * public static Locale[] getAvailableLocales() |
106 * </pre> |
106 * </pre> |
149 * new StringBuffer(), new FieldPosition(0)).toString();</code> |
150 * new StringBuffer(), new FieldPosition(0)).toString();</code> |
150 * </blockquote> |
151 * </blockquote> |
151 * |
152 * |
152 * @param obj The object to format |
153 * @param obj The object to format |
153 * @return Formatted string. |
154 * @return Formatted string. |
154 * @exception IllegalArgumentException if the Format cannot format the given |
155 * @throws IllegalArgumentException if the Format cannot format the given |
155 * object |
156 * object |
156 */ |
157 */ |
157 public final String format (Object obj) { |
158 public final String format (Object obj) { |
158 return format(obj, new StringBuffer(), new FieldPosition(0)).toString(); |
159 return format(obj, new StringBuffer(), new FieldPosition(0)).toString(); |
159 } |
160 } |
160 |
161 |
161 /** |
162 /** |
162 * Formats an object and appends the resulting text to a given string |
163 * Formats an object and appends the resulting text to a given string |
163 * buffer. |
164 * buffer. |
164 * If the <code>pos</code> argument identifies a field used by the format, |
165 * If the {@code pos} argument identifies a field used by the format, |
165 * then its indices are set to the beginning and end of the first such |
166 * then its indices are set to the beginning and end of the first such |
166 * field encountered. |
167 * field encountered. |
167 * |
168 * |
168 * @param obj The object to format |
169 * @param obj The object to format |
169 * @param toAppendTo where the text is to be appended |
170 * @param toAppendTo where the text is to be appended |
170 * @param pos A <code>FieldPosition</code> identifying a field |
171 * @param pos A {@code FieldPosition} identifying a field |
171 * in the formatted text |
172 * in the formatted text |
172 * @return the string buffer passed in as <code>toAppendTo</code>, |
173 * @return the string buffer passed in as {@code toAppendTo}, |
173 * with formatted text appended |
174 * with formatted text appended |
174 * @exception NullPointerException if <code>toAppendTo</code> or |
175 * @throws NullPointerException if {@code toAppendTo} or |
175 * <code>pos</code> is null |
176 * {@code pos} is null |
176 * @exception IllegalArgumentException if the Format cannot format the given |
177 * @throws IllegalArgumentException if the Format cannot format the given |
177 * object |
178 * object |
178 */ |
179 */ |
179 public abstract StringBuffer format(Object obj, |
180 public abstract StringBuffer format(Object obj, |
180 StringBuffer toAppendTo, |
181 StringBuffer toAppendTo, |
181 FieldPosition pos); |
182 FieldPosition pos); |
182 |
183 |
183 /** |
184 /** |
184 * Formats an Object producing an <code>AttributedCharacterIterator</code>. |
185 * Formats an Object producing an {@code AttributedCharacterIterator}. |
185 * You can use the returned <code>AttributedCharacterIterator</code> |
186 * You can use the returned {@code AttributedCharacterIterator} |
186 * to build the resulting String, as well as to determine information |
187 * to build the resulting String, as well as to determine information |
187 * about the resulting String. |
188 * about the resulting String. |
188 * <p> |
189 * <p> |
189 * Each attribute key of the AttributedCharacterIterator will be of type |
190 * Each attribute key of the AttributedCharacterIterator will be of type |
190 * <code>Field</code>. It is up to each <code>Format</code> implementation |
191 * {@code Field}. It is up to each {@code Format} implementation |
191 * to define what the legal values are for each attribute in the |
192 * to define what the legal values are for each attribute in the |
192 * <code>AttributedCharacterIterator</code>, but typically the attribute |
193 * {@code AttributedCharacterIterator}, but typically the attribute |
193 * key is also used as the attribute value. |
194 * key is also used as the attribute value. |
194 * <p>The default implementation creates an |
195 * <p>The default implementation creates an |
195 * <code>AttributedCharacterIterator</code> with no attributes. Subclasses |
196 * {@code AttributedCharacterIterator} with no attributes. Subclasses |
196 * that support fields should override this and create an |
197 * that support fields should override this and create an |
197 * <code>AttributedCharacterIterator</code> with meaningful attributes. |
198 * {@code AttributedCharacterIterator} with meaningful attributes. |
198 * |
199 * |
199 * @exception NullPointerException if obj is null. |
200 * @throws NullPointerException if obj is null. |
200 * @exception IllegalArgumentException when the Format cannot format the |
201 * @throws IllegalArgumentException when the Format cannot format the |
201 * given object. |
202 * given object. |
202 * @param obj The object to format |
203 * @param obj The object to format |
203 * @return AttributedCharacterIterator describing the formatted value. |
204 * @return AttributedCharacterIterator describing the formatted value. |
204 * @since 1.4 |
205 * @since 1.4 |
205 */ |
206 */ |
209 |
210 |
210 /** |
211 /** |
211 * Parses text from a string to produce an object. |
212 * Parses text from a string to produce an object. |
212 * <p> |
213 * <p> |
213 * The method attempts to parse text starting at the index given by |
214 * The method attempts to parse text starting at the index given by |
214 * <code>pos</code>. |
215 * {@code pos}. |
215 * If parsing succeeds, then the index of <code>pos</code> is updated |
216 * If parsing succeeds, then the index of {@code pos} is updated |
216 * to the index after the last character used (parsing does not necessarily |
217 * to the index after the last character used (parsing does not necessarily |
217 * use all characters up to the end of the string), and the parsed |
218 * use all characters up to the end of the string), and the parsed |
218 * object is returned. The updated <code>pos</code> can be used to |
219 * object is returned. The updated {@code pos} can be used to |
219 * indicate the starting point for the next call to this method. |
220 * indicate the starting point for the next call to this method. |
220 * If an error occurs, then the index of <code>pos</code> is not |
221 * If an error occurs, then the index of {@code pos} is not |
221 * changed, the error index of <code>pos</code> is set to the index of |
222 * changed, the error index of {@code pos} is set to the index of |
222 * the character where the error occurred, and null is returned. |
223 * the character where the error occurred, and null is returned. |
223 * |
224 * |
224 * @param source A <code>String</code>, part of which should be parsed. |
225 * @param source A {@code String}, part of which should be parsed. |
225 * @param pos A <code>ParsePosition</code> object with index and error |
226 * @param pos A {@code ParsePosition} object with index and error |
226 * index information as described above. |
227 * index information as described above. |
227 * @return An <code>Object</code> parsed from the string. In case of |
228 * @return An {@code Object} parsed from the string. In case of |
228 * error, returns null. |
229 * error, returns null. |
229 * @throws NullPointerException if {@code source} or {@code pos} is null. |
230 * @throws NullPointerException if {@code source} or {@code pos} is null. |
230 */ |
231 */ |
231 public abstract Object parseObject (String source, ParsePosition pos); |
232 public abstract Object parseObject (String source, ParsePosition pos); |
232 |
233 |
233 /** |
234 /** |
234 * Parses text from the beginning of the given string to produce an object. |
235 * Parses text from the beginning of the given string to produce an object. |
235 * The method may not use the entire text of the given string. |
236 * The method may not use the entire text of the given string. |
236 * |
237 * |
237 * @param source A <code>String</code> whose beginning should be parsed. |
238 * @param source A {@code String} whose beginning should be parsed. |
238 * @return An <code>Object</code> parsed from the string. |
239 * @return An {@code Object} parsed from the string. |
239 * @exception ParseException if the beginning of the specified string |
240 * @throws ParseException if the beginning of the specified string |
240 * cannot be parsed. |
241 * cannot be parsed. |
241 * @throws NullPointerException if {@code source} is null. |
242 * @throws NullPointerException if {@code source} is null. |
242 */ |
243 */ |
243 public Object parseObject(String source) throws ParseException { |
244 public Object parseObject(String source) throws ParseException { |
244 ParsePosition pos = new ParsePosition(0); |
245 ParsePosition pos = new ParsePosition(0); |
361 } |
363 } |
362 } |
364 } |
363 |
365 |
364 |
366 |
365 /** |
367 /** |
366 * FieldDelegate is notified by the various <code>Format</code> |
368 * FieldDelegate is notified by the various {@code Format} |
367 * implementations as they are formatting the Objects. This allows for |
369 * implementations as they are formatting the Objects. This allows for |
368 * storage of the individual sections of the formatted String for |
370 * storage of the individual sections of the formatted String for |
369 * later use, such as in a <code>FieldPosition</code> or for an |
371 * later use, such as in a {@code FieldPosition} or for an |
370 * <code>AttributedCharacterIterator</code>. |
372 * {@code AttributedCharacterIterator}. |
371 * <p> |
373 * <p> |
372 * Delegates should NOT assume that the <code>Format</code> will notify |
374 * Delegates should NOT assume that the {@code Format} will notify |
373 * the delegate of fields in any particular order. |
375 * the delegate of fields in any particular order. |
374 * |
376 * |
375 * @see FieldPosition#getFieldDelegate |
377 * @see FieldPosition#getFieldDelegate |
376 * @see CharacterIteratorFieldDelegate |
378 * @see CharacterIteratorFieldDelegate |
377 */ |
379 */ |
378 interface FieldDelegate { |
380 interface FieldDelegate { |
379 /** |
381 /** |
380 * Notified when a particular region of the String is formatted. This |
382 * Notified when a particular region of the String is formatted. This |
381 * method will be invoked if there is no corresponding integer field id |
383 * method will be invoked if there is no corresponding integer field id |
382 * matching <code>attr</code>. |
384 * matching {@code attr}. |
383 * |
385 * |
384 * @param attr Identifies the field matched |
386 * @param attr Identifies the field matched |
385 * @param value Value associated with the field |
387 * @param value Value associated with the field |
386 * @param start Beginning location of the field, will be >= 0 |
388 * @param start Beginning location of the field, will be >= 0 |
387 * @param end End of the field, will be >= start and <= buffer.length() |
389 * @param end End of the field, will be >= start and <= buffer.length() |