001/**
002 * Unit-API - Units of Measurement API for Java
003 * Copyright (c) 2014 Jean-Marie Dautelle, Werner Keil, V2COM
004 * All rights reserved.
005 *
006 * See LICENSE.txt for details.
007 */
008package javax.measure.format;
009
010import java.io.IOException;
011
012import javax.measure.Unit;
013
014/**
015 * <p>
016 * Formats instances of {@link Unit} to a {@link String} or an {@link Appendable} and parses a {@link CharSequence} to a {@link Unit}.
017 * </p>
018 *
019 * @author <a href="mailto:[email protected]">Jean-Marie Dautelle</a>
020 * @author <a href="mailto:[email protected]">Werner Keil</a>
021 * @version 0.5, Dec 3, 2014
022 *
023 * @see Unit
024 * @see Parser
025 */
026public interface UnitFormat extends Parser<CharSequence, Unit<?>> {
027    /**
028     * Formats the specified unit.
029     *
030     * @param  unit the unit to format.
031     * @param  appendable the appendable destination.
032     * @return the appendable destination passed in with formatted text appended.
033     * @throws IOException if an error occurs while writing to the destination.
034     */
035    Appendable format(Unit<?> unit, Appendable appendable) throws IOException;
036    
037    /**
038     * Parses a portion of the specified {@code CharSequence} from the
039     * specified position to produce a unit. If there is no unit to parse
040     * the unitary unit (dimensionless) is returned.
041     *
042     * @param  csq the {@code CharSequence} to parse.
043     * @return the unit parsed from the specified character sub-sequence.
044     * @throws ParserException if any problem occurs while parsing the
045     *         specified character sequence (e.g. illegal syntax).
046     */
047    Unit<?> parse(CharSequence csq) throws ParserException;
048}