001/*
002 * Units of Measurement API
003 * Copyright (c) 2014-2018, 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 tech.units.indriya.format;
031
032import java.io.IOException;
033import java.text.ParsePosition;
034
035import javax.measure.Quantity;
036import javax.measure.format.ParserException;
037
038/**
039 * <p>
040 * Formats instances of {@link Quantity}.
041 * </p>
042 *
043 * <h1><a name="synchronization">Synchronization</a></h1>
044 * <p>
045 * 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
046 * access a format concurrently, it must be synchronized externally.
047 * <p>
048 *
049 * @author <a href="mailto:werner@uom.technology">Werner Keil</a>
050 * @version 0.3, 26 January, 2018
051 * @since 2.0
052 *
053 * @see Quantity
054 */
055public interface QuantityFormat {
056
057  /**
058   * Formats the specified quantity into an <code>Appendable</code>.
059   *
060   * @param quantity
061   *          the quantity to format.
062   * @param dest
063   *          the appendable destination.
064   * @return the specified <code>Appendable</code>.
065   * @throws IOException
066   *           if an I/O exception occurs.
067   */
068  public Appendable format(Quantity<?> quantity, Appendable dest) throws IOException;
069
070  /**
071   * Parses a portion of the specified <code>CharSequence</code> from the specified position to produce a {@link Quantity}. If parsing succeeds, then
072   * the index of the <code>cursor</code> argument is updated to the index after the last character used.
073   *
074   * @param csq
075   *          the <code>CharSequence</code> to parse.
076   * @param cursor
077   *          the cursor holding the current parsing index.
078   * @return the quantity parsed from the specified character sub-sequence.
079   * @throws IllegalArgumentException
080   *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
081   */
082  public Quantity<?> parse(CharSequence csq, ParsePosition cursor) throws IllegalArgumentException, ParserException;
083
084  /**
085   * Parses a portion of the specified <code>CharSequence</code> from the specified position to produce a {@link Quantity}. If parsing succeeds, then
086   * the index of the <code>cursor</code> argument is updated to the index after the last character used.
087   *
088   * @param csq
089   *          the <code>CharSequence</code> to parse.
090   * @param cursor
091   *          the cursor holding the current parsing index.
092   * @return the quantity parsed from the specified character sub-sequence.
093   * @throws IllegalArgumentException
094   *           if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
095   */
096  public Quantity<?> parse(CharSequence csq) throws ParserException;
097
098  /**
099   * Returns <code>true</code> if this {@link QuantityFormat} depends on a <code>Locale</code> to perform its tasks.
100   * <p>
101   * In environments that do not support a <code>Locale</code>, e.g. Java ME, this usually returns <code>false</code>.
102   * </p>
103   *
104   * @return Whether this format depends on the locale.
105   */
106  default boolean isLocaleSensitive() {
107      return false;
108  }
109}