Package javax.measure.format

Interface UnitFormat

  • public interface UnitFormat
    Formats instances of Unit to a String or Appendable and parses a CharSequence to a Unit.
    Synchronization

    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 access a format concurrently, it must be synchronized externally.

    Since:
    1.0
    Version:
    2.2, May 20, 2023
    Author:
    Jean-Marie Dautelle, Werner Keil
    See Also:
    Unit

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.lang.String format​(Unit<?> unit)
      Formats the specified Unit.
      java.lang.Appendable format​(Unit<?> unit, java.lang.Appendable appendable)
      Formats the specified Unit.
      default boolean isLocaleSensitive()
      Returns true if this UnitFormat depends on a Locale to perform its tasks.
      void label​(Unit<?> unit, java.lang.String label)
      Attaches a system-wide label to the specified Unit.
      Unit<?> parse​(java.lang.CharSequence csq)
      Parses the text into an instance of Unit.
      Unit<?> parse​(java.lang.CharSequence csq, java.text.ParsePosition pos)
      Parses a portion of the specified CharSequence from the specified position to produce a Unit.

    • Method Detail

      • format

        java.lang.Appendable format​(Unit<?> unit,
                            java.lang.Appendable appendable)
                     throws java.io.IOException
        Formats the specified Unit.
        Parameters:
        unit - the Unit to format, not null
        appendable - the appendable destination.
        Returns:
        the appendable destination passed in with formatted text appended.
        Throws:
        java.io.IOException - if an error occurs while writing to the destination.

      • format

        java.lang.String format​(Unit<?> unit)
        Formats the specified Unit.
        Parameters:
        unit - the Unit to format, not null
        Returns:
        the string representation using the settings of this UnitFormat.

      • label

        void label​(Unit<?> unit,
           java.lang.String label)
        Attaches a system-wide label to the specified Unit.

        This method overrides the previous unit's label (e.g. label from unit database or unit system) as units may only have one label. Depending on the UnitFormat implementation, this call may be ignored if the particular unit already has a label.

        If a UnitFormat implementation is explicitly immutable, similar to e.g. the result of Collections.unmodifiableList(), then an UnsupportedOperationException may be thrown upon this call.

        Since UnitFormat implementations often apply the Singleton pattern, system-wide means, the label applies to every instance of UnitFormatA implementing UnitFormat in this case, but not every instance of UnitFormatB or UnitFormatC both also implementing UnitFormat. If a UnitFormat #isLocaleSensitive() it is up to the implementation, whether the label is ignored, applied in a local-neutral manner (in addition to its local-sensitive information) or locale-specific.

        Parameters:
        unit - the unit being labeled.
        label - the new label for this unit.
        Throws:
        java.lang.IllegalArgumentException - if the label is not a valid identifier. This may include characters not supported by a particular UnitFormat implementation (e.g. only ASCII characters for certain devices)
        java.lang.UnsupportedOperationException - if the label operation is not supported by this UnitFormat

      • isLocaleSensitive

        default boolean isLocaleSensitive()
        Returns true if this UnitFormat depends on a Locale to perform its tasks.

        In environments that do not support a Locale, e.g. Java ME, this usually returns false.

        Returns:
        Whether this format depends on a locale.

      • parse

        Unit<?> parse​(java.lang.CharSequence csq,
              java.text.ParsePosition pos)
       throws MeasurementParseException
        Parses a portion of the specified CharSequence from the specified position to produce a Unit. If parsing succeeds, then the index of the pos argument is updated to the index after the last character used.
        Parameters:
        csq - the CharSequence to parse.
        pos - a ParsePosition object holding the current parsing index and error parsing index information as described above.
        Returns:
        the unit parsed from the specified character sub-sequence.
        Throws:
        MeasurementParseException - if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
        Since:
        2.0

      • parse

        Unit<?> parse​(java.lang.CharSequence csq)
       throws MeasurementParseException
        Parses the text into an instance of Unit.

        The parse must complete normally and parse the entire text. If the parse completes without reading the entire length of the text, an exception is thrown. If any other problem occurs during parsing, an exception is thrown.

        Parameters:
        csq - the CharSequence to parse.
        Returns:
        the unit parsed from the specified character sequence.
        Throws:
        MeasurementParseException - if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
        java.lang.UnsupportedOperationException - if the UnitFormat is unable to parse.
        Since:
        2.0