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