OSDN Git Service

* java/text/SimpleDateFormat.java: Re-merged with Classpath.
[pf3gnuchains/gcc-fork.git] / libjava / java / text / NumberFormat.java
1 /* NumberFormat.java -- Formats and parses numbers
2    Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
3
4 This file is part of GNU Classpath.
5
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10  
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19 02111-1307 USA.
20
21 As a special exception, if you link this library with other files to
22 produce an executable, this library does not by itself cause the
23 resulting executable to be covered by the GNU General Public License.
24 This exception does not however invalidate any other reasons why the
25 executable file might be covered by the GNU General Public License. */
26
27
28 package java.text;
29
30 import java.util.Locale;
31 import java.util.ResourceBundle;
32 import java.util.MissingResourceException;
33 import java.io.ObjectInputStream;
34 import java.io.ObjectOutputStream;
35 import java.io.IOException;
36
37 /**
38  * This is the abstract superclass of all classes which format and 
39  * parse numeric values such as decimal numbers, integers, currency values,
40  * and percentages.  These classes perform their parsing and formatting
41  * in a locale specific manner, accounting for such items as differing
42  * currency symbols and thousands separators.
43  * <p>
44  * To create an instance of a concrete subclass of <code>NumberFormat</code>,
45  * do not call a class constructor directly.  Instead, use one of the
46  * static factory methods in this class such as 
47  * <code>getCurrencyInstance</code>.
48  * 
49  * @author Tom Tromey <tromey@cygnus.com>
50  * @author Aaron M. Renn (arenn@urbanophile.com)
51  * @date March 4, 1999
52  */
53 /* Written using "Java Class Libraries", 2nd edition, plus online
54  * API docs for JDK 1.2 from http://www.javasoft.com.
55  * Status:  Believed complete and correct to 1.2, except getAvailableLocales.
56  */
57 public abstract class NumberFormat extends Format implements Cloneable
58 {
59   /**
60    * This is a constant used to create a <code>FieldPosition</code> object
61    * that will return the integer portion of a formatted number.
62    */
63   public static final int INTEGER_FIELD = 0;
64
65   /**
66    * This is a constant used to create a <code>FieldPosition</code> object
67    * that will return the fractional portion of a formatted number.
68    */
69   public static final int FRACTION_FIELD = 1;
70
71   /**
72    * This method is a specialization of the format method that performs
73    * a simple formatting of the specified <code>long</code> number.
74    *
75    * @param number The <code>long</code> to format.
76    *
77    * @return The formatted number
78    */
79   public final String format (long number)
80   {
81     StringBuffer sbuf = new StringBuffer(50);
82     format (number, sbuf, null);
83     return sbuf.toString();
84   }
85
86   public final StringBuffer format (Object obj, StringBuffer sbuf,
87                                     FieldPosition pos)
88   {
89     if (obj instanceof Number)
90       return format(((Number) obj).doubleValue(), sbuf, pos);
91     else
92       throw new IllegalArgumentException 
93         ("Cannot format given Object as a Number");
94   }
95
96   /**
97    * This method formats the specified <code>double</code> and appends it to
98    * a <code>StringBuffer</code>.
99    * 
100    * @param number The <code>double</code> to format.
101    * @param sb The <code>StringBuffer</code> to append the formatted number to.
102    * @param pos The desired <code>FieldPosition</code>.
103    *
104    * @return The <code>StringBuffer</code> with the appended number.
105    */
106   public abstract StringBuffer format (double number,
107                                        StringBuffer sbuf, FieldPosition pos);
108
109   /**
110    * This method formats the specified <code>long</code> and appends it to
111    * a <code>StringBuffer</code>.
112    * 
113    * @param number The <code>long</code> to format.
114    * @param sb The <code>StringBuffer</code> to append the formatted number to.
115    * @param pos The desired <code>FieldPosition</code>.
116    *
117    * @return The <code>StringBuffer</code> with the appended number.
118    */
119   public abstract StringBuffer format (long number,
120                                        StringBuffer sbuf, FieldPosition pos);
121
122   /**
123    * This method tests the specified object for equality against this object.
124    * This will be <code>true</code> if the following conditions are met:
125    * <p>
126    * <ul>
127    * <li>The specified object is not <code>null</code>.
128    * <li>The specified object is an instance of <code>NumberFormat</code>.
129    * </ul>
130    * <p>
131    * Since this method does not test much, it is highly advised that 
132    * concrete subclasses override this method.
133    *
134    * @param obj The <code>Object</code> to test against equality with
135    *            this object. 
136    * 
137    * @return <code>true</code> if the specified object is equal to
138    * this object, <code>false</code> otherwise. 
139    */
140   public boolean equals (Object obj)
141   {
142     if (! (obj instanceof NumberFormat))
143       return false;
144     NumberFormat nf = (NumberFormat) obj;
145     return (groupingUsed == nf.groupingUsed
146             && maximumFractionDigits == nf.maximumFractionDigits
147             && maximumIntegerDigits == nf.maximumIntegerDigits
148             && minimumFractionDigits == nf.minimumFractionDigits
149             && minimumIntegerDigits == nf.minimumIntegerDigits
150             && parseIntegerOnly == nf.parseIntegerOnly);
151   }
152
153   /**
154    * This method returns a list of locales for which concrete instances
155    * of <code>NumberFormat</code> subclasses may be created.
156    *
157    * @return The list of available locales.
158    */
159   public static Locale[] getAvailableLocales ()
160   {
161     Locale[] list = new Locale[1];
162     list[0] = Locale.US;
163     return list;
164   }
165
166   private static final NumberFormat computeInstance (Locale loc,
167                                                      String resource,
168                                                      String def)
169   {
170     ResourceBundle res;
171     try
172       {
173         res = ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
174                                        loc);
175       }
176     catch (MissingResourceException x)
177       {
178         res = null;
179       }
180     String fmt;
181     try
182       {
183         fmt = res == null ? def : res.getString(resource);
184       }
185     catch (MissingResourceException x)
186       {
187         fmt = def;
188       }
189     DecimalFormatSymbols dfs = new DecimalFormatSymbols (loc);
190     return new DecimalFormat (fmt, dfs);
191   }
192
193   /**
194    * This method returns an instance of <code>NumberFormat</code> suitable
195    * for formatting and parsing currency values in the default locale.
196    *
197    * @return An instance of <code>NumberFormat</code> for handling currencies.
198    */
199   public static final NumberFormat getCurrencyInstance ()
200   {
201     return getCurrencyInstance (Locale.getDefault());
202   }
203
204   /**
205    * This method returns an instance of <code>NumberFormat</code> suitable
206    * for formatting and parsing currency values in the specified locale.
207    *
208    * @return An instance of <code>NumberFormat</code> for handling currencies.
209    */
210   public static NumberFormat getCurrencyInstance (Locale loc)
211   {
212     return computeInstance (loc, "currencyFormat", "$#,##0.00;($#,##0.00)");
213   }
214
215   /**
216    * This method returns a default instance for the default locale. This
217    * will be a concrete subclass of <code>NumberFormat</code>, but the 
218    * actual class returned is dependent on the locale.
219    *
220    * @return An instance of the default <code>NumberFormat</code> class.
221    */
222   public static final NumberFormat getInstance ()
223   {
224     return getInstance (Locale.getDefault());
225   }
226
227   /**
228    * This method returns a default instance for the specified locale. This
229    * will be a concrete subclass of <code>NumberFormat</code>, but the 
230    * actual class returned is dependent on the locale.
231    *
232    * @param locale The desired locale.
233    *
234    * @return An instance of the default <code>NumberFormat</code> class.
235    */
236   public static NumberFormat getInstance (Locale loc)
237   {
238     // For now always return a number instance.
239     return getNumberInstance (loc);
240   }
241
242   /**
243    * This method returns the maximum number of digits allowed in the fraction
244    * portion of a number.
245    *
246    * @return The maximum number of digits allowed in the fraction
247    * portion of a number. 
248    */
249   public int getMaximumFractionDigits ()
250   {
251     return maximumFractionDigits;
252   }
253
254   /**
255    * This method returns the maximum number of digits allowed in the integer
256    * portion of a number.
257    *
258    * @return The maximum number of digits allowed in the integer
259    * portion of a number. 
260    */
261   public int getMaximumIntegerDigits ()
262   {
263     return maximumIntegerDigits;
264   }
265
266   /**
267    * This method returns the minimum number of digits allowed in the fraction
268    * portion of a number.
269    *
270    * @return The minimum number of digits allowed in the fraction
271    * portion of a number. 
272    */
273   public int getMinimumFractionDigits ()
274   {
275     return minimumFractionDigits;
276   }
277
278   /**
279    * This method returns the minimum number of digits allowed in the integer
280    * portion of a number.
281    *
282    * @return The minimum number of digits allowed in the integer
283    * portion of a number. 
284    */
285   public int getMinimumIntegerDigits ()
286   {
287     return minimumIntegerDigits;
288   }
289
290   /**
291    * This method returns a default instance for the specified locale. This
292    * will be a concrete subclass of <code>NumberFormat</code>, but the 
293    * actual class returned is dependent on the locale.
294    *
295    * @param locale The desired locale.
296    *
297    * @return An instance of the default <code>NumberFormat</code> class.
298    */
299   public static final NumberFormat getNumberInstance ()
300   {
301     return getNumberInstance (Locale.getDefault());
302   }
303
304   /**
305    * This method returns a general purpose number formatting and parsing
306    * class for the default locale.  This will be a concrete subclass of
307    * <code>NumberFormat</code>, but the actual class returned is dependent
308    * on the locale.
309    *
310    * @return An instance of a generic number formatter for the default locale.
311    */
312   public static NumberFormat getNumberInstance (Locale loc)
313   {
314     return computeInstance (loc, "numberFormat", "#,##0.###");
315   }
316
317   /**
318    * This method returns an instance of <code>NumberFormat</code> suitable
319    * for formatting and parsing percentage values in the default locale.
320    *
321    * @return An instance of <code>NumberFormat</code> for handling percentages.
322    */
323   public static final NumberFormat getPercentInstance ()
324   {
325     return getPercentInstance (Locale.getDefault());
326   }
327
328   /**
329    * This method returns an instance of <code>NumberFormat</code> suitable
330    * for formatting and parsing percentage values in the specified locale.
331    *
332    * @param locale The desired locale.
333    *
334    * @return An instance of <code>NumberFormat</code> for handling percentages.
335    */
336   public static NumberFormat getPercentInstance (Locale loc)
337   {
338     return computeInstance (loc, "percentFormat", "#,##0%");
339   }
340
341   /**
342    * This method returns a hash value for this object.
343    *
344    * @return The hash code.
345    */
346   public int hashCode ()
347   {
348     int hash = super.hashCode();
349     hash ^= (maximumFractionDigits + maximumIntegerDigits
350              + minimumFractionDigits + minimumIntegerDigits);
351     if (groupingUsed)
352       hash ^= 0xf0f0;
353     if (parseIntegerOnly)
354       hash ^= 0x0f0f;
355     return hash;
356   }
357
358   /**
359    * This method tests whether or not grouping is in use.  Grouping is
360    * a method of marking separations in numbers, such as thousand separators
361    * in the US English locale.  The grouping positions and symbols are all
362    * locale specific.  As an example, with grouping disabled, the number one
363    * million would appear as "1000000".  With grouping enabled, this number
364    * might appear as "1,000,000".  (Both of these assume the US English
365    * locale).
366    *
367    * @return <code>true</code> if grouping is enabled,
368    * <code>false</code> otherwise. 
369    */
370   public boolean isGroupingUsed ()
371   {
372     return groupingUsed;
373   }
374
375   /**
376    * This method tests whether or not only integer values should be parsed.
377    * If this class is parsing only integers, parsing stops at the decimal
378    * point.
379    *
380    * @return <code>true</code> if only integers are parsed,
381    * <code>false</code> otherwise. 
382    */
383   public boolean isParseIntegerOnly ()
384   {
385     return parseIntegerOnly;
386   }
387
388   /**
389    * This is a default constructor for use by subclasses.
390    */
391   public NumberFormat ()
392   {
393   }
394
395   /**
396    * This method parses the specified string into a <code>Number</code>.  This
397    * will be a <code>Long</code> if possible, otherwise it will be a
398    * <code>Double</code>.    If no number can be parsed, no exception is
399    * thrown.  Instead, the parse position remains at its initial index.
400    *
401    * @param str The string to parse.
402    * @param pp The desired <code>ParsePosition</code>.
403    *
404    * @return The parsed <code>Number</code>
405    */
406   public abstract Number parse (String sourceStr, ParsePosition pos);
407
408   /**
409    * This method parses the specified string into a <code>Number</code>.  This
410    * will be a <code>Long</code> if possible, otherwise it will be a
411    * <code>Double</code>.  If no number can be parsed, an exception will be
412    * thrown.
413    *
414    * @param str The string to parse.
415    *
416    * @return The parsed <code>Number</code>
417    *
418    * @exception ParseException If no number can be parsed.
419    */
420   public Number parse (String sourceStr) throws ParseException
421   {
422     ParsePosition pp = new ParsePosition (0);
423     Number r = parse (sourceStr, pp);
424     if (r == null)
425       {
426         int index = pp.getErrorIndex();
427         if (index < 0)
428           index = pp.getIndex();
429         throw new ParseException ("couldn't parse number", index);
430       }
431     return r;
432   }
433
434   /**
435    * This method parses the specified string into an <code>Object</code>.  This
436    * will be a <code>Long</code> if possible, otherwise it will be a
437    * <code>Double</code>.    If no number can be parsed, no exception is
438    * thrown.  Instead, the parse position remains at its initial index.
439    *
440    * @param str The string to parse.
441    * @param pp The desired <code>ParsePosition</code>.
442   *
443   * @return The parsed <code>Object</code>
444   */
445   public final Object parseObject (String sourceStr, ParsePosition pos)
446   {
447     return parse (sourceStr, pos);
448   }
449
450   /**
451    * This method sets the grouping behavior of this formatter.  Grouping is
452    * a method of marking separations in numbers, such as thousand separators
453    * in the US English locale.  The grouping positions and symbols are all
454    * locale specific.  As an example, with grouping disabled, the number one
455    * million would appear as "1000000".  With grouping enabled, this number
456    * might appear as "1,000,000".  (Both of these assume the US English
457    * locale).
458    *
459    * @param groupingUsed <code>true</code> to enable grouping,
460    *                     <code>false</code> to disable it. 
461    */
462   public void setGroupingUsed (boolean newValue)
463   {
464     groupingUsed = newValue;
465   }
466
467   /**
468    * This method sets the maximum number of digits allowed in the fraction
469    * portion of a number to the specified value.  If this is less than the
470    * current minimum allowed digits, the minimum allowed digits value will
471    * be lowered to be equal to the new maximum allowed digits value.
472    *
473    * @param maximumFractionDigits The new maximum fraction digits value.
474    */
475   public void setMaximumFractionDigits (int newValue)
476   {
477     maximumFractionDigits = newValue;
478     if (getMinimumFractionDigits () > maximumFractionDigits)
479       setMinimumFractionDigits (maximumFractionDigits);
480   }
481
482   /**
483    * This method sets the maximum number of digits allowed in the integer
484    * portion of a number to the specified value.  If this is less than the
485    * current minimum allowed digits, the minimum allowed digits value will
486    * be lowered to be equal to the new maximum allowed digits value.
487    *
488    * @param maximumIntegerDigits The new maximum integer digits value.
489    */
490   public void setMaximumIntegerDigits (int newValue)
491   {
492     maximumIntegerDigits = newValue;
493     if (getMinimumIntegerDigits () > maximumIntegerDigits)
494       setMinimumIntegerDigits (maximumIntegerDigits);
495   }
496
497   /**
498    * This method sets the minimum number of digits allowed in the fraction
499    * portion of a number to the specified value.  If this is greater than the
500    * current maximum allowed digits, the maximum allowed digits value will
501    * be raised to be equal to the new minimum allowed digits value.
502    *
503    * @param minimumFractionDigits The new minimum fraction digits value.
504    */
505   public void setMinimumFractionDigits (int newValue)
506   {
507     minimumFractionDigits = newValue;
508     if (getMaximumFractionDigits () < minimumFractionDigits)
509       setMaximumFractionDigits (minimumFractionDigits);
510   }
511
512   /**
513    * This method sets the minimum number of digits allowed in the integer
514    * portion of a number to the specified value.  If this is greater than the
515    * current maximum allowed digits, the maximum allowed digits value will
516    * be raised to be equal to the new minimum allowed digits value.
517    *
518    * @param minimumIntegerDigits The new minimum integer digits value.
519    */
520   public void setMinimumIntegerDigits (int newValue)
521   {
522     minimumIntegerDigits = newValue;
523     if (getMaximumIntegerDigits () < minimumIntegerDigits)
524       setMaximumIntegerDigits (minimumIntegerDigits);
525   }
526
527   /** 
528    * This method sets the parsing behavior of this object to parse only 
529    * integers or not.
530    *
531    * @param parseIntegerOnly <code>true</code> to parse only integers,
532    *                         <code>false</code> otherwise. 
533    */
534   public void setParseIntegerOnly (boolean value)
535   {
536     parseIntegerOnly = value;
537   }
538
539   /**
540    * This method is a specialization of the format method that performs
541    * a simple formatting of the specified <code>double</code> number.
542    *
543    * @param number The <code>double</code> to format.
544    *
545    * @return The formatted number
546    */
547   public final String format (double number)
548   {
549     StringBuffer sbuf = new StringBuffer(50);
550     format (number, sbuf, null);
551     return sbuf.toString();
552   }
553
554   // These field names are fixed by the serialization spec.
555   boolean groupingUsed;
556   int maximumFractionDigits;
557   private byte maxFractionDigits;
558   int maximumIntegerDigits;
559   private byte maxIntegerDigits;
560   int minimumFractionDigits;
561   private byte minFractionDigits;
562   int minimumIntegerDigits;
563   private byte minIntegerDigits;
564   boolean parseIntegerOnly;
565   private int serialVersionOnStream;
566   private static final long serialVersionUID = -2308460125733713944L;
567
568   private void readObject(ObjectInputStream stream)
569     throws IOException, ClassNotFoundException
570   {
571     stream.defaultReadObject();
572     if (serialVersionOnStream < 1)
573       {
574         maximumFractionDigits = maxFractionDigits;
575         maximumIntegerDigits = maxIntegerDigits;
576         minimumFractionDigits = minFractionDigits;
577         minimumIntegerDigits = minIntegerDigits;
578         serialVersionOnStream = 1;
579       }
580   }
581
582   private void writeObject(ObjectOutputStream stream) throws IOException
583   {
584     maxFractionDigits = maximumFractionDigits < Byte.MAX_VALUE ?
585       (byte) maximumFractionDigits : Byte.MAX_VALUE;
586     maxIntegerDigits = maximumIntegerDigits < Byte.MAX_VALUE ?
587       (byte) maximumIntegerDigits : Byte.MAX_VALUE;
588     minFractionDigits = minimumFractionDigits < Byte.MAX_VALUE ?
589       (byte) minimumFractionDigits : Byte.MAX_VALUE;
590     minIntegerDigits = minimumIntegerDigits < Byte.MAX_VALUE ?
591       (byte) minimumIntegerDigits : Byte.MAX_VALUE;
592     serialVersionOnStream = 1;
593     stream.defaultWriteObject();
594   }
595 }