ucar.units.UnitFormat Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of udunits Show documentation

The ucar.units Java package is for decoding and encoding formatted unit specifications (e.g. "m/s"), converting numeric values between compatible units (e.g. between "m/s" and "knot"), and for performing arithmetic operations on units (e.g. dividing one unit by another, or raising a unit to a power).

The newest version!

/*
 * Copyright (c) 1998-2018 University Corporation for Atmospheric Research/Unidata
 * See LICENSE for license information.
 */
package ucar.units;

/**
 * Interface for classes that parse and format unit specifications.
 *
 * @author Steven R. Emmerson
 */
public interface
UnitFormat
{
    /**
     * Parses a unit specification.
     * @param spec		The unit specification (e.g. "m/s");
     * @return			The unit corresponding to the specification.
     * @throws NoSuchUnitException	A unit in the specification couldn't be
     *					found (e.g. the "m" in the example).
     * @throws UnitParseException	The specification is grammatically
     *					incorrect.
     * @throws SpecificationException	The specification is incorrect somehow.
     * @throws UnitDBException		Problem with the unit database.
     * @throws PrefixDBException	Problem with the unit-prefix database.
     * @throws UnitSystemException	Problem with the system of units.
     */
    public Unit
    parse(String spec)
	throws NoSuchUnitException,
	    UnitParseException,
	    SpecificationException,
	    UnitDBException,
	    PrefixDBException,
	    UnitSystemException;

    /**
     * Parses a unit specification.
     * @param spec		The unit specification (e.g. "m/s");
     * @param unitDB		The unit database.
     * @return			The unit corresponding to the specification.
     * @throws NoSuchUnitException	A unit in the specification couldn't be
     *					found (e.g. the "m" in the example).
     * @throws UnitParseException	The specification is grammatically
     *					incorrect.
     * @throws SpecificationException	The specification is incorrect somehow.
     * @throws UnitDBException		Problem with the unit database.
     * @throws PrefixDBException	Problem with the unit-prefix database.
     * @throws UnitSystemException	Problem with the system of units.
     */
    public Unit
    parse(String spec, UnitDB unitDB)
	throws NoSuchUnitException,
	    UnitParseException,
	    SpecificationException,
	    UnitDBException,
	    PrefixDBException,
	    UnitSystemException;

    /**
     * Formats a Factor (a base unit/exponent pair).
     * @param factor		The base unit/exponent pair.
     * @return			The formatted factor.
     */
    public String
    format(Factor factor);

    /**
     * Appends a formatted factor to a string buffer.  A factor is a
     * base unit/exponent pair).
     * @param factor		The base unit/exponent pair.
     * @param buffer		The string buffer to be appended to.
     * @return			The string buffer.
     */
    public StringBuffer
    format(Factor factor, StringBuffer buffer);

    /**
     * Formats a unit.  If the unit has a symbol or name, then one of them
     * will be used; otherwise, a specification of the unit in terms of
     * underlying units will be returned.
     * @param unit		The unit.
     * @return			The formatted unit.
     */
    public String
    format(Unit unit)
	throws UnitClassException;

    /**
     * Formats a unit using a long form.  This always returns a specification
     * for the unit in terms of underlying units: it doesn't return the name
     * or symbol of the unit unless the unit is a base unit.
     * @param unit		The unit.
     * @return			The formatted unit.
     */
    public String
    longFormat(Unit unit)
	throws UnitClassException;

    /**
     * Appends a formatted unit to a string buffer.  This is similar to
     * format(Unit) but it appends the specification to a
     * string buffer.
     * @param unit		The unit.
     * @param buffer		The string buffer to be appended to.
     * @return			The string buffer.
     */
    public StringBuffer
    format(Unit unit, StringBuffer buffer)
	throws UnitClassException;

    /**
     * Appends a unit formatted according to the long form to a string buffer.
     * This is similar to longFormat(Unit) but it appends the
     * specification to a string buffer.
     * @param unit		The unit.
     * @param buffer		The string buffer to be appended to.
     * @return			The string buffer.
     */
    public StringBuffer
    longFormat(Unit unit, StringBuffer buffer)
	throws UnitClassException;
}