Class NumberWithUnit

  • All Implemented Interfaces:
    Serializable

    public class NumberWithUnit
    extends Object
    implements Serializable

    A class that combines a value with a unit.

    This class can be used to work with values that have an associated unit. For instance spaces in a layout can be defined in arbitrary units like pixels, dialog units, inches or centimeters. To support this, an instance of this class stores a value (as a floating point number) and a reference to a Unit object. This Unit object is also used to perform conversions of the stored value to the default unit pixels.

    Instances of this class are immutable. Once created, they cannot be changed any more. Thus they can be shared between multiple threads.

    Version:
    $Id: NumberWithUnit.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    See Also:
    Serialized Form
    • Field Detail

      • ZERO

        public static final NumberWithUnit ZERO
        Constant for the special value zero.
    • Constructor Detail

      • NumberWithUnit

        public NumberWithUnit​(int val)
        Creates a new instance of NumberWithUnit with the given value and the unit pixels.
        Parameters:
        val - the value
      • NumberWithUnit

        public NumberWithUnit​(double val,
                              Unit unit)
        Creates a new instance of NumberWithUnit and initializes it.
        Parameters:
        val - the numeric value
        unit - the unit (must not be null )
      • NumberWithUnit

        public NumberWithUnit​(String s)
        Creates a new instance of NumberWithUnit and initializes it from the given string representation. The string passed to this method must start with a valid double number. Then after optional whitespace the name of the unit must follow. If no unit is provided, pixel is assumed. Valid strings are for instance "10", "10cm", "10.5 cm".
        Parameters:
        s - the string to be parsed (must not be null)
        Throws:
        IllegalArgumentException - if the passed in string is not a valid unit string
        See Also:
        toUnitString()
    • Method Detail

      • getValue

        public final double getValue()
        Returns the numeric value.
        Returns:
        the value
      • getUnit

        public final Unit getUnit()
        Returns the unit of this number.
        Returns:
        the unit
      • toPixel

        public int toPixel​(UnitSizeHandler handler,
                           Object comp,
                           boolean y)
        Converts this number into a pixel value. This method calls the corresponding conversion method on the actual Unit object.
        Parameters:
        handler - the size handler
        comp - the component
        y - flag for X or Y direction
        Returns:
        the pixel value
        See Also:
        Unit.toPixel(double, UnitSizeHandler, Object, boolean)
      • buildUnitString

        public void buildUnitString​(StringBuilder buf)
        Appends a string representation of this number and its unit to the given string buffer. First the number is written and then the name of the unit. This is the same as toUnitString(), but the string is directly appended to the given buffer.
        Parameters:
        buf - the string buffer (must not be null)
        Throws:
        IllegalArgumentException - if the buffer is null
      • toUnitString

        public String toUnitString()
        Returns a string representation for the stored value and the unit. This string contains the value immediately followed by the short unit name, e.g. 10px, 100dlu, 2.5in. Strings in this format can be passed to the constructor that takes a string argument.
        Returns:
        a string for the value and the unit
      • toString

        public String toString()
        Returns a string representation of this object.
        Overrides:
        toString in class Object
        Returns:
        a string for this object
      • hashCode

        public int hashCode()
        Returns a hash code for this object.
        Overrides:
        hashCode in class Object
        Returns:
        a hash code
      • equals

        public boolean equals​(Object obj)
        Compares two objects. Two instances of this class are equal if they have the same unit and the same value.
        Overrides:
        equals in class Object
        Parameters:
        obj - the object to compare to
        Returns:
        a flag if the objects are equal
      • nonNull

        public static NumberWithUnit nonNull​(NumberWithUnit n)
        A convenience method for performing checks for null values. This method converts a null argument into an instance with the value 0. Other arguments are directly returned. This is useful if null references are to be avoided.
        Parameters:
        n - the source number
        Returns:
        the guaranteed non null result number