View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.fraction;
19  
20  import java.io.Serializable;
21  import java.text.FieldPosition;
22  import java.text.Format;
23  import java.text.NumberFormat;
24  import java.text.ParseException;
25  import java.text.ParsePosition;
26  import java.util.Locale;
27  
28  import org.apache.commons.math.ConvergenceException;
29  
30  /**
31   * Formats a Fraction number in proper format or improper format.  The number
32   * format for each of the whole number, numerator and, denominator can be
33   * configured.
34   *
35   * @since 1.1
36   * @version $Revision: 506713 $ $Date: 2007-02-12 15:35:08 -0700 (Mon, 12 Feb 2007) $
37   */
38  public class FractionFormat extends Format implements Serializable {
39      
40      /** Serializable version identifier */
41      private static final long serialVersionUID = -6337346779577272306L;
42  
43      /** The format used for the denominator. */
44      private NumberFormat denominatorFormat;
45  
46      /** The format used for the numerator. */
47      private NumberFormat numeratorFormat;
48      
49      /**
50       * Create an improper formatting instance with the default number format
51       * for the numerator and denominator.  
52       */
53      public FractionFormat() {
54          this(getDefaultNumberFormat());
55      }
56  
57      /**
58       * Create an improper formatting instance with a custom number format for
59       * both the numerator and denominator.
60       * @param format the custom format for both the numerator and denominator.
61       */
62      public FractionFormat(NumberFormat format) {
63          this(format, (NumberFormat)format.clone());
64      }
65  
66      /**
67       * Create an improper formatting instance with a custom number format for
68       * the numerator and a custom number format for the denominator.
69       * @param numeratorFormat the custom format for the numerator.
70       * @param denominatorFormat the custom format for the denominator.
71       */
72      public FractionFormat(NumberFormat numeratorFormat,
73              NumberFormat denominatorFormat)
74      {
75          super();
76          this.numeratorFormat = numeratorFormat;
77          this.denominatorFormat = denominatorFormat;
78      }
79  
80      /**
81       * This static method calls formatFraction() on a default instance of
82       * FractionFormat.
83       *
84       * @param f Fraction object to format
85       * @return A formatted fraction in proper form.
86       */
87      public static String formatFraction(Fraction f) {
88          return getImproperInstance().format(f);
89      }
90      
91      /**
92       * Get the set of locales for which complex formats are available.  This
93       * is the same set as the {@link NumberFormat} set. 
94       * @return available complex format locales.
95       */
96      public static Locale[] getAvailableLocales() {
97          return NumberFormat.getAvailableLocales();
98      }
99      
100     /**
101      * Returns the default complex format for the current locale.
102      * @return the default complex format.
103      */
104     public static FractionFormat getImproperInstance() {
105         return getImproperInstance(Locale.getDefault());
106     }
107     
108     /**
109      * Returns the default complex format for the given locale.
110      * @param locale the specific locale used by the format.
111      * @return the complex format specific to the given locale.
112      */
113     public static FractionFormat getImproperInstance(Locale locale) {
114         NumberFormat f = getDefaultNumberFormat(locale);
115         return new FractionFormat(f);
116     }
117     
118     /**
119      * Returns the default complex format for the current locale.
120      * @return the default complex format.
121      */
122     public static FractionFormat getProperInstance() {
123         return getProperInstance(Locale.getDefault());
124     }
125     
126     /**
127      * Returns the default complex format for the given locale.
128      * @param locale the specific locale used by the format.
129      * @return the complex format specific to the given locale.
130      */
131     public static FractionFormat getProperInstance(Locale locale) {
132         NumberFormat f = getDefaultNumberFormat(locale);
133         return new ProperFractionFormat(f);
134     }
135     
136     /**
137      * Create a default number format.  The default number format is based on
138      * {@link NumberFormat#getNumberInstance(java.util.Locale)} with the only
139      * customizing is the maximum number of fraction digits, which is set to 0.  
140      * @return the default number format.
141      */
142     protected static NumberFormat getDefaultNumberFormat() {
143         return getDefaultNumberFormat(Locale.getDefault());
144     }
145     
146     /**
147      * Create a default number format.  The default number format is based on
148      * {@link NumberFormat#getNumberInstance(java.util.Locale)} with the only
149      * customizing is the maximum number of fraction digits, which is set to 0.  
150      * @param locale the specific locale used by the format.
151      * @return the default number format specific to the given locale.
152      */
153     private static NumberFormat getDefaultNumberFormat(Locale locale) {
154         NumberFormat nf = NumberFormat.getNumberInstance(locale);
155         nf.setMaximumFractionDigits(0);
156         nf.setParseIntegerOnly(true);
157         return nf;
158     }
159     
160     /**
161      * Formats a {@link Fraction} object to produce a string.  The fraction is
162      * output in improper format.
163      *
164      * @param fraction the object to format.
165      * @param toAppendTo where the text is to be appended
166      * @param pos On input: an alignment field, if desired. On output: the
167      *            offsets of the alignment field
168      * @return the value passed in as toAppendTo.
169      */
170     public StringBuffer format(Fraction fraction, StringBuffer toAppendTo,
171             FieldPosition pos) {
172         
173         pos.setBeginIndex(0);
174         pos.setEndIndex(0);
175 
176         getNumeratorFormat().format(fraction.getNumerator(), toAppendTo, pos);
177         toAppendTo.append(" / ");
178         getDenominatorFormat().format(fraction.getDenominator(), toAppendTo,
179             pos);
180         
181         return toAppendTo;
182     }
183     
184     /**
185      * Formats a object to produce a string.  <code>obj</code> must be either a 
186      * {@link Fraction} object or a {@link Number} object.  Any other type of
187      * object will result in an {@link IllegalArgumentException} being thrown.
188      *
189      * @param obj the object to format.
190      * @param toAppendTo where the text is to be appended
191      * @param pos On input: an alignment field, if desired. On output: the
192      *            offsets of the alignment field
193      * @return the value passed in as toAppendTo.
194      * @see java.text.Format#format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)
195      * @throws IllegalArgumentException is <code>obj</code> is not a valid type.
196      */
197     public StringBuffer format(Object obj, StringBuffer toAppendTo,
198             FieldPosition pos)
199     {
200         StringBuffer ret = null;
201         
202         if (obj instanceof Fraction) {
203             ret = format( (Fraction)obj, toAppendTo, pos);
204         } else if (obj instanceof Number) {
205             try {
206                 ret = format( new Fraction(((Number)obj).doubleValue()),
207                     toAppendTo, pos);
208             } catch (ConvergenceException ex) {
209                 throw new IllegalArgumentException(
210                     "Cannot convert given object to a fraction.");
211             }
212         } else { 
213             throw new IllegalArgumentException(
214                 "Cannot format given object as a fraction");
215         }
216         
217         return ret;
218     }
219 
220     /**
221      * Access the denominator format.
222      * @return the denominator format.
223      */
224     public NumberFormat getDenominatorFormat() {
225         return denominatorFormat;
226     }
227     
228     /**
229      * Access the numerator format.
230      * @return the numerator format.
231      */
232     public NumberFormat getNumeratorFormat() {
233         return numeratorFormat;
234     }
235 
236     /**
237      * Parses a string to produce a {@link Fraction} object.
238      * @param source the string to parse
239      * @return the parsed {@link Fraction} object.
240      * @exception ParseException if the beginning of the specified string
241      *            cannot be parsed.
242      */
243     public Fraction parse(String source) throws ParseException {
244         ParsePosition parsePosition = new ParsePosition(0);
245         Fraction result = parse(source, parsePosition);
246         if (parsePosition.getIndex() == 0) {
247             throw new ParseException("Unparseable fraction number: \"" +
248                 source + "\"", parsePosition.getErrorIndex());
249         }
250         return result;
251     }
252     
253     /**
254      * Parses a string to produce a {@link Fraction} object.  This method
255      * expects the string to be formatted as an improper fraction.  
256      * @param source the string to parse
257      * @param pos input/ouput parsing parameter.
258      * @return the parsed {@link Fraction} object.
259      */
260     public Fraction parse(String source, ParsePosition pos) {
261         int initialIndex = pos.getIndex();
262 
263         // parse whitespace
264         parseAndIgnoreWhitespace(source, pos);
265 
266         // parse numerator
267         Number num = getNumeratorFormat().parse(source, pos);
268         if (num == null) {
269             // invalid integer number
270             // set index back to initial, error index should already be set
271             // character examined.
272             pos.setIndex(initialIndex);
273             return null;
274         }
275 
276         // parse '/'
277         int startIndex = pos.getIndex();
278         char c = parseNextCharacter(source, pos);
279         switch (c) {
280         case 0 :
281             // no '/'
282             // return num as a fraction
283             return new Fraction(num.intValue(), 1);
284         case '/' :
285             // found '/', continue parsing denominator
286             break;
287         default :
288             // invalid '/'
289             // set index back to initial, error index should be the last
290             // character examined.
291             pos.setIndex(initialIndex);
292             pos.setErrorIndex(startIndex);
293             return null;
294         }
295 
296         // parse whitespace
297         parseAndIgnoreWhitespace(source, pos);
298 
299         // parse denominator
300         Number den = getDenominatorFormat().parse(source, pos);
301         if (den == null) {
302             // invalid integer number
303             // set index back to initial, error index should already be set
304             // character examined.
305             pos.setIndex(initialIndex);
306             return null;
307         }
308 
309         return new Fraction(num.intValue(), den.intValue());
310     }
311 
312     /**
313      * Parses a string to produce a object.
314      * @param source the string to parse
315      * @param pos input/ouput parsing parameter.
316      * @return the parsed object.
317      * @see java.text.Format#parseObject(java.lang.String, java.text.ParsePosition)
318      */
319     public Object parseObject(String source, ParsePosition pos) {
320         return parse(source, pos);
321     }
322     
323     /**
324      * Modify the denominator format.
325      * @param format the new denominator format value.
326      * @throws IllegalArgumentException if <code>format</code> is
327      *         <code>null</code>.
328      */
329     public void setDenominatorFormat(NumberFormat format) {
330         if (format == null) {
331             throw new IllegalArgumentException(
332                 "denominator format can not be null.");
333         }
334         this.denominatorFormat = format;
335     }
336     
337     /**
338      * Modify the numerator format.
339      * @param format the new numerator format value.
340      * @throws IllegalArgumentException if <code>format</code> is
341      *         <code>null</code>.
342      */
343     public void setNumeratorFormat(NumberFormat format) {
344         if (format == null) {
345             throw new IllegalArgumentException(
346                 "numerator format can not be null.");
347         }
348         this.numeratorFormat = format;
349     }
350      
351     /**
352      * Parses <code>source</code> until a non-whitespace character is found.
353      * @param source the string to parse
354      * @param pos input/ouput parsing parameter.  On output, <code>pos</code>
355      *        holds the index of the next non-whitespace character.
356      */
357     protected static void parseAndIgnoreWhitespace(
358         String source, ParsePosition pos)
359     {
360         parseNextCharacter(source, pos);
361         pos.setIndex(pos.getIndex() - 1);
362     }
363 
364     /**
365      * Parses <code>source</code> until a non-whitespace character is found.
366      * @param source the string to parse
367      * @param pos input/ouput parsing parameter.
368      * @return the first non-whitespace character.
369      */
370     protected static char parseNextCharacter(String source, ParsePosition pos) {
371          int index = pos.getIndex();
372          int n = source.length();
373          char ret = 0;
374 
375          if (index < n) {
376              char c;
377              do {
378                  c = source.charAt(index++);
379              } while (Character.isWhitespace(c) && index < n);
380              pos.setIndex(index);
381          
382              if (index < n) {
383                  ret = c;
384              }
385          }
386          
387          return ret;
388     }
389 }