/*

 * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved

 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved

 *

 *   The original version of this source code and documentation is copyrighted

 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These

 * materials are provided under terms of a License Agreement between Taligent

 * and Sun. This technology is protected by multiple US and International

 * patents. This notice and attribution to Taligent may not be removed.

 *   Taligent is a registered trademark of Taligent, Inc.

 *

 */

package java.text;

import java.io.InvalidObjectException;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.math.BigInteger;

import java.math.RoundingMode;

import java.text.spi.NumberFormatProvider;

import java.util.Currency;

import java.util.HashMap;

import java.util.Hashtable;

import java.util.Locale;

import java.util.Map;

import java.util.ResourceBundle;

import java.util.concurrent.atomic.AtomicInteger;

import java.util.concurrent.atomic.AtomicLong;

import java.util.spi.LocaleServiceProvider;

import sun.util.LocaleServiceProviderPool;

import sun.util.resources.LocaleData;

/**

 * <code>NumberFormat</code> is the abstract base class for all number

 * formats. This class provides the interface for formatting and parsing

 * numbers. <code>NumberFormat</code> also provides methods for determining

 * which locales have number formats, and what their names are.

 *

 * <p>

 * <code>NumberFormat</code> helps you to format and parse numbers for any locale.

 * Your code can be completely independent of the locale conventions for

 * decimal points, thousands-separators, or even the particular decimal

 * digits used, or whether the number format is even decimal.

 *

 * <p>

 * To format a number for the current Locale, use one of the factory

 * class methods:

 * <blockquote>

 * <pre>

 *  myString = NumberFormat.getInstance().format(myNumber);

 * </pre>

 * </blockquote>

 * If you are formatting multiple numbers, it is

 * more efficient to get the format and use it multiple times so that

 * the system doesn't have to fetch the information about the local

 * language and country conventions multiple times.

 * <blockquote>

 * <pre>

 * NumberFormat nf = NumberFormat.getInstance();

 * for (int i = 0; i < myNumber.length; ++i) {

 *     output.println(nf.format(myNumber[i]) + "; ");

 * }

 * </pre>

 * </blockquote>

 * To format a number for a different Locale, specify it in the

 * call to <code>getInstance</code>.

 * <blockquote>

 * <pre>

 * NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);

 * </pre>

 * </blockquote>

 * You can also use a <code>NumberFormat</code> to parse numbers:

 * <blockquote>

 * <pre>

 * myNumber = nf.parse(myString);

 * </pre>

 * </blockquote>

 * Use <code>getInstance</code> or <code>getNumberInstance</code> to get the

 * normal number format. Use <code>getIntegerInstance</code> to get an

 * integer number format. Use <code>getCurrencyInstance</code> to get the

 * currency number format. And use <code>getPercentInstance</code> to get a

 * format for displaying percentages. With this format, a fraction like

 * 0.53 is displayed as 53%.

 *

 * <p>

 * You can also control the display of numbers with such methods as

 * <code>setMinimumFractionDigits</code>.

 * If you want even more control over the format or parsing,

 * or want to give your users more control,

 * you can try casting the <code>NumberFormat</code> you get from the factory methods

 * to a <code>DecimalFormat</code>. This will work for the vast majority

 * of locales; just remember to put it in a <code>try</code> block in case you

 * encounter an unusual one.

 *

 * <p>

 * NumberFormat and DecimalFormat are designed such that some controls

 * work for formatting and others work for parsing.  The following is

 * the detailed description for each these control methods,

 * <p>

 * setParseIntegerOnly : only affects parsing, e.g.

 * if true,  "3456.78" -> 3456 (and leaves the parse position just after index 6)

 * if false, "3456.78" -> 3456.78 (and leaves the parse position just after index 8)

 * This is independent of formatting.  If you want to not show a decimal point

 * where there might be no digits after the decimal point, use

 * setDecimalSeparatorAlwaysShown.

 * <p>

 * setDecimalSeparatorAlwaysShown : only affects formatting, and only where

 * there might be no digits after the decimal point, such as with a pattern

 * like "#,##0.##", e.g.,

 * if true,  3456.00 -> "3,456."

 * if false, 3456.00 -> "3456"

 * This is independent of parsing.  If you want parsing to stop at the decimal

 * point, use setParseIntegerOnly.

 *

 * <p>

 * You can also use forms of the <code>parse</code> and <code>format</code>

 * methods with <code>ParsePosition</code> and <code>FieldPosition</code> to

 * allow you to:

 * <ul>

 * <li> progressively parse through pieces of a string

 * <li> align the decimal point and other areas

 * </ul>

 * For example, you can align numbers in two ways:

 * <ol>

 * <li> If you are using a monospaced font with spacing for alignment,

 *      you can pass the <code>FieldPosition</code> in your format call, with

 *      <code>field</code> = <code>INTEGER_FIELD</code>. On output,

 *      <code>getEndIndex</code> will be set to the offset between the

 *      last character of the integer and the decimal. Add

 *      (desiredSpaceCount - getEndIndex) spaces at the front of the string.

 *

 * <li> If you are using proportional fonts,

 *      instead of padding with spaces, measure the width

 *      of the string in pixels from the start to <code>getEndIndex</code>.

 *      Then move the pen by

 *      (desiredPixelWidth - widthToAlignmentPoint) before drawing the text.

 *      It also works where there is no decimal, but possibly additional

 *      characters at the end, e.g., with parentheses in negative

 *      numbers: "(12)" for -12.

 * </ol>

 *

 * <h4><a name="synchronization">Synchronization</a></h4>

 *

 * <p>

 * Number formats are generally not synchronized.

 * It is recommended to create separate format instances for each thread.

 * If multiple threads access a format concurrently, it must be synchronized

 * externally.

 *

 * @see          DecimalFormat

 * @see          ChoiceFormat

 * @author       Mark Davis

 * @author       Helena Shih

 */

public abstract class NumberFormat extends Format  {

    /**

     * Field constant used to construct a FieldPosition object. Signifies that

     * the position of the integer part of a formatted number should be returned.

     * @see java.text.FieldPosition

     */

    public static final int INTEGER_FIELD = 0;

    /**

     * Field constant used to construct a FieldPosition object. Signifies that

     * the position of the fraction part of a formatted number should be returned.

     * @see java.text.FieldPosition

     */

    public static final int FRACTION_FIELD = 1;

    /**

     * Sole constructor.  (For invocation by subclass constructors, typically

     * implicit.)

     */

    protected NumberFormat() {

    }

    /**

     * Formats a number and appends the resulting text to the given string

     * buffer.

     * The number can be of any subclass of {@link java.lang.Number}.

     * <p>

     * This implementation extracts the number's value using

     * {@link java.lang.Number#longValue()} for all integral type values that

     * can be converted to <code>long</code> without loss of information,

     * including <code>BigInteger</code> values with a

     * {@link java.math.BigInteger#bitLength() bit length} of less than 64,

     * and {@link java.lang.Number#doubleValue()} for all other types. It

     * then calls

     * {@link #format(long,java.lang.StringBuffer,java.text.FieldPosition)}

     * or {@link #format(double,java.lang.StringBuffer,java.text.FieldPosition)}.

     * This may result in loss of magnitude information and precision for

     * <code>BigInteger</code> and <code>BigDecimal</code> values.

     * @param number     the number to format

     * @param toAppendTo the <code>StringBuffer</code> to which the formatted

     *                   text is to be appended

     * @param pos        On input: an alignment field, if desired.

     *                   On output: the offsets of the alignment field.

     * @return           the value passed in as <code>toAppendTo</code>

     * @exception        IllegalArgumentException if <code>number</code> is

     *                   null or not an instance of <code>Number</code>.

     * @exception        NullPointerException if <code>toAppendTo</code> or

     *                   <code>pos</code> is null

     * @exception        ArithmeticException if rounding is needed with rounding

     *                   mode being set to RoundingMode.UNNECESSARY

     * @see              java.text.FieldPosition

     */

    public StringBuffer format(Object number,

                               StringBuffer toAppendTo,

                               FieldPosition pos) {

        if (number instanceof Long || number instanceof Integer ||

            number instanceof Short || number instanceof Byte ||

            number instanceof AtomicInteger || number instanceof AtomicLong ||

            (number instanceof BigInteger &&

             ((BigInteger)number).bitLength() < 64)) {

            return format(((Number)number).longValue(), toAppendTo, pos);

        } else if (number instanceof Number) {

            return format(((Number)number).doubleValue(), toAppendTo, pos);

        } else {

            throw new IllegalArgumentException("Cannot format given Object as a Number");

        }

    }

    /**

     * Parses text from a string to produce a <code>Number</code>.

     * <p>

     * The method attempts to parse text starting at the index given by

     * <code>pos</code>.

     * If parsing succeeds, then the index of <code>pos</code> is updated

     * to the index after the last character used (parsing does not necessarily

     * use all characters up to the end of the string), and the parsed

     * number is returned. The updated <code>pos</code> can be used to

     * indicate the starting point for the next call to this method.

     * If an error occurs, then the index of <code>pos</code> is not

     * changed, the error index of <code>pos</code> is set to the index of

     * the character where the error occurred, and null is returned.

     * <p>

     * See the {@link #parse(String, ParsePosition)} method for more information

     * on number parsing.

     *

     * @param source A <code>String</code>, part of which should be parsed.

     * @param pos A <code>ParsePosition</code> object with index and error

     *            index information as described above.

     * @return A <code>Number</code> parsed from the string. In case of

     *         error, returns null.

     * @exception NullPointerException if <code>pos</code> is null.

     */

    public final Object parseObject(String source, ParsePosition pos) {

        return parse(source, pos);

    }

   /**

     * Specialization of format.

     * @exception        ArithmeticException if rounding is needed with rounding

     *                   mode being set to RoundingMode.UNNECESSARY

     * @see java.text.Format#format

     */

    public final String format(double number) {

        return format(number, new StringBuffer(),

                      DontCareFieldPosition.INSTANCE).toString();

    }

   /**

     * Specialization of format.

     * @exception        ArithmeticException if rounding is needed with rounding

     *                   mode being set to RoundingMode.UNNECESSARY

     * @see java.text.Format#format

     */

    public final String format(long number) {

        return format(number, new StringBuffer(),

                      DontCareFieldPosition.INSTANCE).toString();

    }

   /**

     * Specialization of format.

     * @exception        ArithmeticException if rounding is needed with rounding

     *                   mode being set to RoundingMode.UNNECESSARY

     * @see java.text.Format#format

     */

    public abstract StringBuffer format(double number,

                                        StringBuffer toAppendTo,

                                        FieldPosition pos);

   /**

     * Specialization of format.

     * @exception        ArithmeticException if rounding is needed with rounding

     *                   mode being set to RoundingMode.UNNECESSARY

     * @see java.text.Format#format

     */

    public abstract StringBuffer format(long number,

                                        StringBuffer toAppendTo,

                                        FieldPosition pos);

   /**

     * Returns a Long if possible (e.g., within the range [Long.MIN_VALUE,

     * Long.MAX_VALUE] and with no decimals), otherwise a Double.

     * If IntegerOnly is set, will stop at a decimal

     * point (or equivalent; e.g., for rational numbers "1 2/3", will stop

     * after the 1).

     * Does not throw an exception; if no object can be parsed, index is

     * unchanged!

     * @see java.text.NumberFormat#isParseIntegerOnly

     * @see java.text.Format#parseObject

     */

    public abstract Number parse(String source, ParsePosition parsePosition);

    /**

     * Parses text from the beginning of the given string to produce a number.

     * The method may not use the entire text of the given string.

     * <p>

     * See the {@link #parse(String, ParsePosition)} method for more information

     * on number parsing.

     *

     * @param source A <code>String</code> whose beginning should be parsed.

     * @return A <code>Number</code> parsed from the string.

     * @exception ParseException if the beginning of the specified string

     *            cannot be parsed.

     */

    public Number parse(String source) throws ParseException {

        ParsePosition parsePosition = new ParsePosition(0);

        Number result = parse(source, parsePosition);

        if (parsePosition.index == 0) {

            throw new ParseException("Unparseable number: \"" + source + "\"",

                                     parsePosition.errorIndex);

        }

        return result;

    }

    /**

     * Returns true if this format will parse numbers as integers only.

     * For example in the English locale, with ParseIntegerOnly true, the

     * string "1234." would be parsed as the integer value 1234 and parsing

     * would stop at the "." character.  Of course, the exact format accepted

     * by the parse operation is locale dependant and determined by sub-classes

     * of NumberFormat.

     */

    public boolean isParseIntegerOnly() {

        return parseIntegerOnly;

    }

    /**

     * Sets whether or not numbers should be parsed as integers only.

     * @see #isParseIntegerOnly

     */

    public void setParseIntegerOnly(boolean value) {

        parseIntegerOnly = value;

    }

    //============== Locale Stuff =====================

    /**

     * Returns a general-purpose number format for the current default locale.

     * This is the same as calling

     * {@link #getNumberInstance() getNumberInstance()}.

     */

    public final static NumberFormat getInstance() {

        return getInstance(Locale.getDefault(Locale.Category.FORMAT), NUMBERSTYLE);

    }

    /**

     * Returns a general-purpose number format for the specified locale.

     * This is the same as calling

     * {@link #getNumberInstance(java.util.Locale) getNumberInstance(inLocale)}.

     */

    public static NumberFormat getInstance(Locale inLocale) {

        return getInstance(inLocale, NUMBERSTYLE);

    }

    /**

     * Returns a general-purpose number format for the current default locale.

     */

    public final static NumberFormat getNumberInstance() {

        return getInstance(Locale.getDefault(Locale.Category.FORMAT), NUMBERSTYLE);

    }

    /**

     * Returns a general-purpose number format for the specified locale.

     */

    public static NumberFormat getNumberInstance(Locale inLocale) {

        return getInstance(inLocale, NUMBERSTYLE);

    }

    /**

     * Returns an integer number format for the current default locale. The

     * returned number format is configured to round floating point numbers

     * to the nearest integer using half-even rounding (see {@link

     * java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}) for formatting,

     * and to parse only the integer part of an input string (see {@link

     * #isParseIntegerOnly isParseIntegerOnly}).

     *

     * @see #getRoundingMode()

     * @return a number format for integer values

     * @since 1.4

     */

    public final static NumberFormat getIntegerInstance() {

        return getInstance(Locale.getDefault(Locale.Category.FORMAT), INTEGERSTYLE);

    }

    /**

     * Returns an integer number format for the specified locale. The

     * returned number format is configured to round floating point numbers

     * to the nearest integer using half-even rounding (see {@link

     * java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}) for formatting,

     * and to parse only the integer part of an input string (see {@link

     * #isParseIntegerOnly isParseIntegerOnly}).

     *

     * @see #getRoundingMode()

     * @return a number format for integer values

     * @since 1.4

     */

    public static NumberFormat getIntegerInstance(Locale inLocale) {

        return getInstance(inLocale, INTEGERSTYLE);

    }

    /**

     * Returns a currency format for the current default locale.

     */

    public final static NumberFormat getCurrencyInstance() {

        return getInstance(Locale.getDefault(Locale.Category.FORMAT), CURRENCYSTYLE);

    }

    /**

     * Returns a currency format for the specified locale.

     */

    public static NumberFormat getCurrencyInstance(Locale inLocale) {

        return getInstance(inLocale, CURRENCYSTYLE);

    }

    /**

     * Returns a percentage format for the current default locale.

     */

    public final static NumberFormat getPercentInstance() {

        return getInstance(Locale.getDefault(Locale.Category.FORMAT), PERCENTSTYLE);

    }

    /**

     * Returns a percentage format for the specified locale.

     */

    public static NumberFormat getPercentInstance(Locale inLocale) {

        return getInstance(inLocale, PERCENTSTYLE);

    }

    /**

     * Returns a scientific format for the current default locale.

     */

    /*public*/ final static NumberFormat getScientificInstance() {

        return getInstance(Locale.getDefault(Locale.Category.FORMAT), SCIENTIFICSTYLE);

    }

    /**

     * Returns a scientific format for the specified locale.

     */

    /*public*/ static NumberFormat getScientificInstance(Locale inLocale) {

        return getInstance(inLocale, SCIENTIFICSTYLE);

    }

    /**

     * Returns an array of all locales for which the

     * <code>get*Instance</code> methods of this class can return

     * localized instances.

     * The returned array represents the union of locales supported by the Java

     * runtime and by installed

     * {@link java.text.spi.NumberFormatProvider NumberFormatProvider} implementations.

     * It must contain at least a <code>Locale</code> instance equal to

     * {@link java.util.Locale#US Locale.US}.

     *

     * @return An array of locales for which localized

     *         <code>NumberFormat</code> instances are available.

     */

    public static Locale[] getAvailableLocales() {

        LocaleServiceProviderPool pool =

            LocaleServiceProviderPool.getPool(NumberFormatProvider.class);

        return pool.getAvailableLocales();

    }

    /**

     * Overrides hashCode

     */

    public int hashCode() {

        return maximumIntegerDigits * 37 + maxFractionDigits;

        // just enough fields for a reasonable distribution

    }

    /**

     * Overrides equals

     */

    public boolean equals(Object obj) {

        if (obj == null) {

            return false;

        }

        if (this == obj) {

            return true;

        }

        if (getClass() != obj.getClass()) {

            return false;

        }

        NumberFormat other = (NumberFormat) obj;

        return (maximumIntegerDigits == other.maximumIntegerDigits

            && minimumIntegerDigits == other.minimumIntegerDigits