/*

 * Copyright (c) 1996, 2017, 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.locale.provider.LocaleProviderAdapter;

import sun.util.locale.provider.LocaleServiceProviderPool;

/**

 * <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>{@code

 * 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>{@code

 * 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>{@code

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

 * }</pre>

 * </blockquote>

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

 * <blockquote>

 * <pre>{@code

 * 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>

 *

 * <h3><a id="synchronization">Synchronization</a></h3>

 *

 * <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.

 *

 * @implSpec The {@link #format(double, StringBuffer, FieldPosition)},

 * {@link #format(long, StringBuffer, FieldPosition)} and

 * {@link #parse(String, ParsePosition)} methods may throw

 * {@code NullPointerException}, if any of their parameter is {@code null}.

 * The subclass may provide its own implementation and specification about

 * {@code NullPointerException}.

 *

 * <p>

 * The default implementation provides rounding modes defined

 * in {@link java.math.RoundingMode} for formatting numbers. It

 * uses the {@linkplain java.math.RoundingMode#HALF_EVEN

 * round half-even algorithm}. To change the rounding mode use

 * {@link #setRoundingMode(java.math.RoundingMode) setRoundingMode}.

 * The {@code NumberFormat} returned by the static factory methods is

 * configured to round floating point numbers using half-even

 * rounding (see {@link java.math.RoundingMode#HALF_EVEN

 * RoundingMode.HALF_EVEN}) for formatting.

 *

 * @see          DecimalFormat

 * @see          ChoiceFormat

 * @author       Mark Davis

 * @author       Helena Shih

 * @since 1.1

 */

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

     * @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

     */

    @Override

    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.

     * @throws NullPointerException if {@code source} or {@code pos} is null.

     */

    @Override

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

        return parse(source, pos);

    }

   /**

     * Specialization of format.

     *

     * @param number the double number to format

     * @return the formatted String

     * @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) {

        // Use fast-path for double result if that works

        String result = fastFormat(number);

        if (result != null)

            return result;

        return format(number, new StringBuffer(),

                      DontCareFieldPosition.INSTANCE).toString();

    }

    /*

     * fastFormat() is supposed to be implemented in concrete subclasses only.

     * Default implem always returns null.

     */

    String fastFormat(double number) { return null; }

   /**

     * Specialization of format.

     *

     * @param number the long number to format

     * @return the formatted String

     * @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.

     *

     * @param number     the double number to format

     * @param toAppendTo the StringBuffer to which the formatted text is to be

     *                   appended

     * @return the formatted StringBuffer

     * @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.

     *

     * @param number     the long number to format

     * @param toAppendTo the StringBuffer to which the formatted text is to be

     *                   appended

     * @return the formatted StringBuffer

     * @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!

     *

     * @param source the String to parse

     * @param parsePosition the parse position

     * @return the parsed value

     * @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 dependent and determined by sub-classes

     * of NumberFormat.

     *

     * @return {@code true} if numbers should be parsed as integers only;

     *         {@code false} otherwise

     */

    public boolean isParseIntegerOnly() {

        return parseIntegerOnly;

    }

    /**

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

     *

     * @param value {@code true} if numbers should be parsed as integers only;

     *              {@code false} otherwise

     * @see #isParseIntegerOnly

     */

    public void setParseIntegerOnly(boolean value) {

        parseIntegerOnly = value;

    }

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

    /**

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

     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.

     * This is the same as calling

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

     *

     * @return the {@code NumberFormat} instance for general-purpose number

     * formatting

     */

    public static final 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)}.

     *

     * @param inLocale the desired locale

     * @return the {@code NumberFormat} instance for general-purpose number

     * formatting

     */

    public static NumberFormat getInstance(Locale inLocale) {

        return getInstance(inLocale, NUMBERSTYLE);

    }

    /**

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

     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.

     * <p>This is equivalent to calling

     * {@link #getNumberInstance(Locale)

     *     getNumberInstance(Locale.getDefault(Locale.Category.FORMAT))}.

     *

     * @return the {@code NumberFormat} instance for general-purpose number

     * formatting

     * @see java.util.Locale#getDefault(java.util.Locale.Category)

     * @see java.util.Locale.Category#FORMAT

     */

    public static final NumberFormat getNumberInstance() {

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

    }

    /**

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

     *

     * @param inLocale the desired locale

     * @return the {@code NumberFormat} instance for general-purpose number

     * formatting

     */

    public static NumberFormat getNumberInstance(Locale inLocale) {

        return getInstance(inLocale, NUMBERSTYLE);

    }

    /**

     * Returns an integer number format for the current default

     * {@link java.util.Locale.Category#FORMAT FORMAT} locale. The

     * returned number format is configured to round floating point numbers