/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package freemarker.core;

import java.text.NumberFormat;

import freemarker.template.TemplateDateModel;
import freemarker.template.TemplateModelException;
import freemarker.template.TemplateNumberModel;

Represents a number format; used in templates for formatting and parsing with that format. This is similar to Java's NumberFormat, but made to fit the requirements of FreeMarker. Also, it makes easier to define formats that can't be represented with Java's existing NumberFormat implementations. 
 Implementations need not be thread-safe if the TemplateNumberFormatFactory doesn't recycle them among different Environment-s. As far as FreeMarker's concerned, instances are bound to a single Environment, and Environment-s are thread-local objects. 
Since:
2.3.24/**
 * Represents a number format; used in templates for formatting and parsing with that format. This is similar to Java's
 * {@link NumberFormat}, but made to fit the requirements of FreeMarker. Also, it makes easier to define formats that
 * can't be represented with Java's existing {@link NumberFormat} implementations.
 * 
 * <p>
 * Implementations need not be thread-safe if the {@link TemplateNumberFormatFactory} doesn't recycle them among
 * different {@link Environment}-s. As far as FreeMarker's concerned, instances are bound to a single
 * {@link Environment}, and {@link Environment}-s are thread-local objects.
 * 
 * @since 2.3.24
 */
public abstract class TemplateNumberFormat extends TemplateValueFormat {

    
Params:
numberModel –  The number to format; not null. Most implementations will just work with the return value of TemplateDateModel.getAsDate(), but some may format differently depending on the properties of a custom TemplateDateModel implementation.
Throws:
TemplateValueFormatException –  If any problem occurs while parsing/getting the format. Notable subclass: UnformattableValueException.
TemplateModelException –  Exception thrown by the dateModel object when calling its methods.
Returns:
The number as text, with no escaping (like no HTML escaping); can't be null./**
     * @param numberModel
     *            The number to format; not {@code null}. Most implementations will just work with the return value of
     *            {@link TemplateDateModel#getAsDate()}, but some may format differently depending on the properties of
     *            a custom {@link TemplateDateModel} implementation.
     *            
     * @return The number as text, with no escaping (like no HTML escaping); can't be {@code null}.
     * 
     * @throws TemplateValueFormatException
     *             If any problem occurs while parsing/getting the format. Notable subclass:
     *             {@link UnformattableValueException}.
     * @throws TemplateModelException
     *             Exception thrown by the {@code dateModel} object when calling its methods.
     */
    public abstract String formatToPlainText(TemplateNumberModel numberModel)
            throws TemplateValueFormatException, TemplateModelException;

    
Formats the model to markup instead of to plain text if the result markup will be more than just plain text escaped, otherwise falls back to formatting to plain text. If the markup result would be just the result of formatToPlainText(TemplateNumberModel) escaped, it must return the String that formatToPlainText(TemplateNumberModel) does. 
 The implementation in TemplateNumberFormat simply calls formatToPlainText(TemplateNumberModel). 
Returns:
A String or a TemplateMarkupOutputModel; not null./**
     * Formats the model to markup instead of to plain text if the result markup will be more than just plain text
     * escaped, otherwise falls back to formatting to plain text. If the markup result would be just the result of
     * {@link #formatToPlainText(TemplateNumberModel)} escaped, it must return the {@link String} that
     * {@link #formatToPlainText(TemplateNumberModel)} does.
     * 
     * <p>
     * The implementation in {@link TemplateNumberFormat} simply calls {@link #formatToPlainText(TemplateNumberModel)}.
     * 
     * @return A {@link String} or a {@link TemplateMarkupOutputModel}; not {@code null}.
     */
    public Object format(TemplateNumberModel numberModel)
            throws TemplateValueFormatException, TemplateModelException {
        return formatToPlainText(numberModel);
    }
    
    
Tells if this formatter should be re-created if the locale changes.
/**
     * Tells if this formatter should be re-created if the locale changes.
     */
    public abstract boolean isLocaleBound();

    
This method is reserved for future purposes; currently it always throws ParsingNotSupportedException. We don't yet support number parsing with TemplateNumberFormat-s, because currently FTL parses strings to number with the ArithmeticEngine (TemplateNumberFormat were only introduced in 2.3.24). If it will be support, it will be similar to TemplateDateFormat.parse(String, int). /**
     * This method is reserved for future purposes; currently it always throws {@link ParsingNotSupportedException}. We
     * don't yet support number parsing with {@link TemplateNumberFormat}-s, because currently FTL parses strings to
     * number with the {@link ArithmeticEngine} ({@link TemplateNumberFormat} were only introduced in 2.3.24). If it
     * will be support, it will be similar to {@link TemplateDateFormat#parse(String, int)}.
     */
    public final Object parse(String s) throws TemplateValueFormatException {
        throw new ParsingNotSupportedException("Number formats currenly don't support parsing");
    }
    
    
}