001/*
002 * Units of Measurement API
003 * Copyright (c) 2014-2023, Jean-Marie Dautelle, Werner Keil, Otavio Santana.
004 *
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without modification,
008 * are permitted provided that the following conditions are met:
009 *
010 * 1. Redistributions of source code must retain the above copyright notice,
011 *    this list of conditions and the following disclaimer.
012 *
013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
014 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
015 *
016 * 3. Neither the name of JSR-385 nor the names of its contributors may be used to endorse or promote products
017 *    derived from this software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package javax.measure.format;
031
032import java.io.IOException;
033import java.text.ParsePosition;
034
035import javax.measure.Quantity;
036
037/**
038 * Formats instances of {@link Quantity}.
039 *
040 * <dl>
041 * <dt><span class="strong"><a id="synchronization">Synchronization</a></span></dt>
042 * </dl>
043 * Instances of this class are not required to be thread-safe. It is recommended to use separate format instances for each thread. If multiple threads
044 * access a format concurrently, it must be synchronized externally.
045 *
046 * @author <a href="mailto:werner@uom.technology">Werner Keil</a>
047 * @author <a href="mailto:thodoris.bais@gmail.com">Thodoris Bais</a>
048 *
049 * @version 1.1, 20 May, 2023
050 * @since 2.0
051 *
052 * @see Quantity
053 */
054public interface QuantityFormat {
055
056    /**
057     * Formats the specified quantity into an {@code Appendable}.
058     *
059     * @param quantity
060     *          the quantity to format.
061     * @param destination
062     *          the appendable destination.
063     * @return the specified {@code Appendable}.
064     * @throws IOException
065     *           if an I/O exception occurs.
066     */
067    public Appendable format(Quantity<?> quantity, Appendable destination) throws IOException;
068
069    /**
070     * Formats the specified {@link Quantity}.
071     *
072     * @param quantity
073     *            the {@link Quantity} to format, not {@code null}
074     * @return the string representation using the settings of this {@link QuantityFormat}.
075     */
076    String format(Quantity<?> quantity);
077
078    /**
079     * Parses a portion of the specified {@code CharSequence} from the specified position to produce a {@link Quantity}.
080     * If parsing succeeds, then the index of the {@code pos} argument is updated to the index after the last character used.
081     *
082     * @param csq
083     *          the {@code CharSequence} to parse.
084     * @param pos
085     *          a ParsePosition object holding the current parsing index and error parsing index information as described above.
086     * @return the quantity parsed from the specified character sub-sequence.
087     * @throws MeasurementParseException
088     *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
089     */
090    public Quantity<?> parse(CharSequence csq, ParsePosition pos) throws MeasurementParseException;
091
092    /**
093     * Parses the specified {@code CharSequence} to produce a {@link Quantity}.
094     * <p>
095     * The parse must complete normally and parse the entire text. If the parse completes without reading the entire length of the text, an exception
096     * is thrown. If any other problem occurs during parsing, an exception is thrown.
097     * </p>
098     *
099     * @param csq
100     *          the {@code CharSequence} to parse.
101     * @return the quantity parsed from the specified character sub-sequence.
102     * @throws MeasurementParseException
103     *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
104     */
105    public Quantity<?> parse(CharSequence csq) throws MeasurementParseException;
106
107    /**
108     * Returns {@code true} if this {@link QuantityFormat} depends on a {@code Locale} to perform its tasks.
109     * <p>
110     * In environments that do not support a {@code Locale}, e.g. Java ME, this usually returns {@code false}.
111     * </p>
112     *
113     * @return whether this format depends on the locale.
114     */
115    default boolean isLocaleSensitive() {
116        return false;
117    }
118}