de.vc.util

## Class Measure

- java.lang.Object
- - de.vc.util.Measure

- All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable

      public class Measure
      extends java.lang.Object
      implements java.lang.Cloneable, java.lang.Comparable

  A measure represents an absolute or relative length, width or value. A measure can be immutable, this means it cannot be modified using `add`, `subtract` and `scale`. You should create immutable measures using the factory because the factory caches measures. This can be very helpful to safe memory.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Measure.Factory` The factory creates immutable measure and caches them.
    `static class` | `Measure.Unit` Represents a unit.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Measure.Unit` | `CM` Unit CM
    `static Measure.Unit` | `EMU` Unit EMU (12700 EMU = 1 Point)
    `static Measure.Unit` | `INCH` Unit Inch
    `static Measure.Unit` | `MM` Unit MM
    `static Measure.Unit` | `PERCENTAGE` Unit Percentage (relative)
    `static Measure.Unit` | `POINTS` Unit Points
    `static Measure.Unit` | `TWIPS` Unit Twips

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Measure(Measure.Unit unit, double value)` Creates a measure.
    `Measure(Measure.Unit unit, double value, int scaling)` Creates a measure.
    `Measure(Measure.Unit unit, double value, Measure.Unit preferedOutputUnit)` Creates a measure.
    `Measure(java.lang.String value)` Creates a measure by parsing the given string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Measure` | `add(Measure m)` Adds the given Measure to this Measure and returns a new measure object.
    `Measure` | `add(java.lang.String value)` Adds the given value to this Measure and returns a new measure object.
    `void` | `changeUnit(Measure.Unit u)` Changes the unit and the value is updated related to given unit.
    `Measure` | `cloned()` Clones this measure.
    `int` | `compareTo(java.lang.Object o)`
    `static double` | `convert(Measure.Unit fromUnit, double fromValue, Measure.Unit toUnit)`
    `static boolean` | `equals(Measure m1, Measure m2)` Tests, if two measures are equal.
    `boolean` | `equals(java.lang.Object o)` Checks for equality.
    `double` | `getCM()`
    `double` | `getInch()`
    `double` | `getPercentage()`
    `double` | `getPoints()`
    `Measure.Unit` | `getPreferredUnit()` Deprecated. Use getUnit()
    `int` | `getScaling()`
    `Measure.Unit` | `getUnit()`
    `double` | `getValue(Measure.Unit unit)` Gets the value for a given unit.
    `double` | `getValue(Measure.Unit unit, int roundIdx)` Gets the value for a given unit and round it.
    `int` | `hashCode()`
    `boolean` | `isEqual(Measure m)` Tests, if `m`is equal to `this`measure.````
    `boolean` | `isGreater(Measure m)` Tests, if `this`is greater than `m`.````
    `boolean` | `isLess(Measure m)` Tests, if `this`is less than `m`.````
    `boolean` | `isRelativ()` Tests, if this measure is relative (e.g. percentage).
    `static Measure` | `max(Measure m1, Measure m2)` Determinates the maximum of given measures.
    `Measure` | `multiply(double factor)` Scales this measure.
    `Measure` | `negate()` Gets a negated value of this measure.
    `void` | `setPreferredUnit(Measure.Unit unit)` Deprecated. Use changeUnit
    `void` | `setScaling(int scale)`
    `int` | `signum()` Returns the signum function of this Measure.
    `Measure` | `subtract(Measure m)` Subtracts the given Measure from this measure and returns a new measure object.
    `Measure` | `subtract(java.lang.String value)` Subtracts `value` from this measure and returns a new measure object.
    `java.lang.String` | `toString()` Gets a string-representation of this measure.
    `java.lang.String` | `toString(int precision)` Gets a string-representation of this measure.
    `java.lang.String` | `toString(Measure.Unit unit)` Gets a string representation in given unit.
    `java.lang.String` | `toString(Measure.Unit unit, int precision)` Gets a rounded string representation in given unit.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### CM

          public static final Measure.Unit CM

      Unit CM

    - #### MM

          public static final Measure.Unit MM

      Unit MM

    - #### POINTS

          public static final Measure.Unit POINTS

      Unit Points

    - #### TWIPS

          public static final Measure.Unit TWIPS

      Unit Twips

    - #### INCH

          public static final Measure.Unit INCH

      Unit Inch

    - #### PERCENTAGE

          public static final Measure.Unit PERCENTAGE

      Unit Percentage (relative)

    - #### EMU

          public static final Measure.Unit EMU

      Unit EMU (12700 EMU = 1 Point)

  - ### Constructor Detail

    - #### Measure

          public Measure(java.lang.String value)

      Creates a measure by parsing the given string. If the given string is not understood, an IllegalArgumentException is thrown.
      Possible units are: "cm", "mm", "pt", "twips", "inch", "%". If no unit is given unit "points" is taken.
      Parameters:
        `value` - String representation.

    - #### Measure

          public Measure(Measure.Unit unit,
                 double value)

      Creates a measure.
      Parameters:
        `unit` - Unit of the value.
        `value` - Value.

    - #### Measure

          public Measure(Measure.Unit unit,
                 double value,
                 Measure.Unit preferedOutputUnit)

      Creates a measure.
      Parameters:
        `unit` - Unit of the value.
        `value` - Value.
        `preferedOutputUnit` - Unit used by toString()-Methodes.

    - #### Measure

          public Measure(Measure.Unit unit,
                 double value,
                 int scaling)

      Creates a measure.
      Parameters:
        `unit` - Unit of the value.
        `value` - Value.
        `scaling` - Scale of value.

  - ### Method Detail

    - #### equals

          public boolean equals(java.lang.Object o)

      Checks for equality.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `o` - Object to check.
      Returns:
        `true`, if `o` is a measure with equal length.

    - #### isGreater

          public boolean isGreater(Measure m)

      Tests, if `this`is greater than `m`.````
      Parameters:
        `m` - Measure
      Returns:
        `true`if greater.``

    - #### isLess

          public boolean isLess(Measure m)

      Tests, if `this`is less than `m`.````
      Parameters:
        `m` - Measure
      Returns:
        `true`if less.``

    - #### isEqual

          public boolean isEqual(Measure m)

      Tests, if `m`is equal to `this`measure.````
      Parameters:
        `m` - Measure
      Returns:
        `true`if equal.``

    - #### getValue

          public double getValue(Measure.Unit unit)

      Gets the value for a given unit.
      Parameters:
        `unit` - Unit.
      Returns:
        double value.

    - #### getPoints

          public double getPoints()

    - #### getCM

          public double getCM()

    - #### getInch

          public double getInch()

    - #### getPercentage

          public double getPercentage()

    - #### getValue

          public double getValue(Measure.Unit unit,
                        int roundIdx)

      Gets the value for a given unit and round it.
      Parameters:
        `unit` - Unit.
        `roundIdx` - Round index (decimal places)
      Returns:
        double value.

    - #### toString

          public java.lang.String toString()

      Gets a string-representation of this measure. If this measure is relativ a percentage (e.g. 23%) otherwise points (e.g. 16pt) are delivered.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        String representation.

    - #### toString

          public java.lang.String toString(int precision)

      Gets a string-representation of this measure. If this measure is relativ a percentage (e.g. 23%) otherwise points (e.g. 16pt) are delivered.
      Parameters:
        `precision` - The optional number of decimal digits to round to.
      Returns:
        String representation.

    - #### toString

          public java.lang.String toString(Measure.Unit unit)

      Gets a string representation in given unit.
      Parameters:
        `unit` - Unit.
      Returns:
        String String.

    - #### toString

          public java.lang.String toString(Measure.Unit unit,
                                  int precision)

      Gets a rounded string representation in given unit.
      Parameters:
        `unit` - Unit.
        `precision` - The optional number of decimal digits to round to.
      Returns:
        String String.

    - #### multiply

          public Measure multiply(double factor)

      Scales this measure.
      Parameters:
        `factor` - Scale-Factor.
      Throws:
        `java.lang.IllegalArgumentException` - if immutable.

    - #### isRelativ

          public boolean isRelativ()

      Tests, if this measure is relative (e.g. percentage).
      Returns:
        boolean Measure is relative.

    - #### add

          public Measure add(Measure m)

      Adds the given Measure to this Measure and returns a new measure object. This measure is NOT modified.
      Parameters:
        `m` - Measure.
      Returns:
        Summe.

    - #### add

          public Measure add(java.lang.String value)

      Adds the given value to this Measure and returns a new measure object. This measure is NOT modified.
      Parameters:
        `value` - Value to add.
      Returns:
        Summe.

    - #### subtract

          public Measure subtract(Measure m)

      Subtracts the given Measure from this measure and returns a new measure object. This measure is NOT modified.
      Parameters:
        `m` - Measure.
      Returns:
        Measure.

    - #### subtract

          public Measure subtract(java.lang.String value)

      Subtracts `value` from this measure and returns a new measure object. This measure is NOT modified.
      Parameters:
        `value` - Value to subtract.
      Returns:
        Measure.

    - #### cloned

          public Measure cloned()

      Clones this measure. A cloned measure is always mutable.
      Returns:
        Cloned measure.

    - #### max

          public static Measure max(Measure m1,
                    Measure m2)

      Determinates the maximum of given measures. You should only compare measure of the same type (relative or non-relative).
      Parameters:
        `m1` - Measure one.
        `m2` - Measure two.
      Returns:
        Maximum of measures.

    - #### equals

          public static boolean equals(Measure m1,
                       Measure m2)

      Tests, if two measures are equal. Returns also true if both are `null`.
      Parameters:
        `m1` - First measure.
        `m2` - Second measure.
      Returns:
        `true`, if equal.

    - #### convert

          public static double convert(Measure.Unit fromUnit,
                       double fromValue,
                       Measure.Unit toUnit)

    - #### changeUnit

          public void changeUnit(Measure.Unit u)

      Changes the unit and the value is updated related to given unit.
      Parameters:
        `u` -

    - #### getUnit

          public Measure.Unit getUnit()

      Returns:
        Unit

    - #### getPreferredUnit

          public Measure.Unit getPreferredUnit()

      Deprecated. Use getUnit()
      Gets the preferred unit of this measure.
      Returns:
        Preferred unit.

    - #### setPreferredUnit

          public void setPreferredUnit(Measure.Unit unit)

      Deprecated. Use changeUnit
      Sets the preferred unit of this measure.
      Parameters:
        `unit` - Preferred unit.

    - #### setScaling

          public void setScaling(int scale)

    - #### getScaling

          public int getScaling()

    - #### negate

          public Measure negate()

      Gets a negated value of this measure.
      Returns:
        Measure Negated measure.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### signum

          public int signum()

      Returns the signum function of this Measure.
      Returns:
        -1, 0 or 1 as the value of this Measure is negative, zero or positive.

    - #### compareTo

          public int compareTo(java.lang.Object o)

      Specified by:
        `compareTo` in interface `java.lang.Comparable`

© 2003-2011 by Sascha Schmidt (vision-cloud.de). All Rights Reserved.