de.caff.util.measure

## Class PhysicalLength

- java.lang.Object
- - de.caff.util.measure.PhysicalLength

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<PhysicalLength>

      public final class PhysicalLength
      extends java.lang.Object
      implements java.io.Serializable, java.lang.Comparable<PhysicalLength>

  A physical length.

  This is an immutable class.

  Author:
    Rammi
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PhysicalLength` | `NULL` Null length.
    `static java.lang.String` | `UNIT_FORMAT` The format for printing units.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PhysicalLength(double value, LengthUnit unit)` Create a new physical length.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(PhysicalLength o)` Compares this object with the specified object for order.
    `PhysicalLength` | `dividedBy(double divider)` Get a divided part of this physical length.
    `double` | `dividedBy(PhysicalLength physicalLength)` Get the scaling between two physical lengths.
    `boolean` | `equals(java.lang.Object o)` Is this length equal to another one?
    `boolean` | `equals(PhysicalLength other, PhysicalLength epsilon)` Is this length nearly equal to another one?
    `static PhysicalLength` | `fromString(java.lang.String descr)` Decodes a physical length description in text form,using the default locale.
    `static PhysicalLength` | `fromString(java.lang.String descr, java.util.Locale locale)` Decodes a physical length description in text form.
    `static PhysicalLength` | `ft(double feet)` Factory method for lengths in foot.
    `double` | `getLength()` Get the length.
    `double` | `getLength(LengthUnit targetUnit)` Get the length in an arbitrary unit.
    `double` | `getLengthInMeter()` Get the length in meter.
    `LengthUnit` | `getUnit()` Get the length unit.
    `int` | `hashCode()` Getr a useful hashcode.
    `static PhysicalLength` | `in(double inches)` Factory method for lengths in inches.
    `PhysicalLength` | `in(LengthUnit targetUnit)` Get this length in another unit.
    `static PhysicalLength` | `m(double meter)` Factory method for lengths in meter.
    `static void` | `main(java.lang.String[] args)`
    `PhysicalLength` | `minus(PhysicalLength another)` Get the difference of this physical length and another.
    `static PhysicalLength` | `mm(double millimeter)` Factory method for lengths in millimeter.
    `PhysicalLength` | `plus(PhysicalLength another)` Get the sum of this physical length and another.
    `PhysicalLength` | `times(double scale)` Get a scaled physical length.
    `java.lang.String` | `toString()` Return a string representation of this length.
    `java.lang.String` | `toString(LengthUnit targetUnit)` Return a string representation of this length using the given unit.
    `java.lang.String` | `toString(LengthUnit targetUnit, java.util.Locale locale)` Return a string representation of this length using the given unit.
    `java.lang.String` | `toString(java.util.Locale locale)` Return a string representation of this length.

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

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

- - ### Field Detail

    - #### UNIT_FORMAT

          @NotNull
          public static final java.lang.String UNIT_FORMAT

      The format for printing units.
      See Also:
        Constant Field Values

    - #### NULL

          @NotNull
          public static final PhysicalLength NULL

      Null length.

  - ### Constructor Detail

    - #### PhysicalLength

          public PhysicalLength(double value,
                                @NotNull
                                LengthUnit unit)

      Create a new physical length.
      Parameters:
        `value` - length value
        `unit` - length unit

  - ### Method Detail

    - #### getUnit

          public LengthUnit getUnit()

      Get the length unit.
      Returns:
        length unit

    - #### getLengthInMeter

          public double getLengthInMeter()

      Get the length in meter.
      Returns:
        length im meter

    - #### getLength

          public double getLength()

      Get the length.
      Returns:
        length in `unit`

    - #### getLength

          public double getLength(@NotNull
                                  LengthUnit targetUnit)

      Get the length in an arbitrary unit.
      Parameters:
        `targetUnit` - length unit for return value
      Returns:
        the length in the given value

    - #### toString

          public java.lang.String toString()

      Return a string representation of this length. This uses the default locale.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        length in internal unit as string

    - #### toString

          public java.lang.String toString(@NotNull
                                           LengthUnit targetUnit)

      Return a string representation of this length using the given unit.
      Parameters:
        `targetUnit` - length unit
      Returns:
        length in unit as string

    - #### toString

          public java.lang.String toString(@NotNull
                                           java.util.Locale locale)

      Return a string representation of this length.
      Parameters:
        `locale` - locale to use for number output
      Returns:
        length in internal unit as string

    - #### toString

          public java.lang.String toString(@NotNull
                                           LengthUnit targetUnit,
                                           @NotNull
                                           java.util.Locale locale)

      Return a string representation of this length using the given unit.
      Parameters:
        `targetUnit` - length unit
        `locale` - locale to use for number output
      Returns:
        length in unit as string

    - #### equals

          public boolean equals(@NotNull
                                PhysicalLength other,
                                @NotNull
                                PhysicalLength epsilon)

      Is this length nearly equal to another one?
      Parameters:
        `other` - length unit to compare to
        `epsilon` - the maximal error allowed
      Returns:
        `true` if the lengths are nearly equal, otherwise `false`

    - #### equals

          public boolean equals(java.lang.Object o)

      Is this length equal to another one?
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `o` - object to compare to
      Returns:
        `true` if the lengths are equals, otherwise `false`

    - #### hashCode

          public int hashCode()

      Getr a useful hashcode.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        hash code

    - #### times

          @NotNull
          public PhysicalLength times(double scale)

      Get a scaled physical length.
      Parameters:
        `scale` - scaling factor
      Returns:
        a physical length which is scale times this physical length

    - #### dividedBy

          @NotNull
          public PhysicalLength dividedBy(double divider)

      Get a divided part of this physical length. Because a physical length is internally just a double all rules which apply for doubles apply here (like division by zero etc).
      Parameters:
        `divider` - divider
      Returns:
        this physical length divided by divider

    - #### dividedBy

          public double dividedBy(@NotNull
                                  PhysicalLength physicalLength)

      Get the scaling between two physical lengths. Because a physical length is internally just a double all rules which apply for doubles apply here (like division by zero etc).
      Parameters:
        `physicalLength` - other length
      Returns:
        scale: this/physicalLength

    - #### plus

          @NotNull
          public PhysicalLength plus(@NotNull
                                              PhysicalLength another)

      Get the sum of this physical length and another.
      Parameters:
        `another` - another physical length
      Returns:
        this + another

    - #### minus

          @NotNull
          public PhysicalLength minus(@NotNull
                                               PhysicalLength another)

      Get the difference of this physical length and another.
      Parameters:
        `another` - another physical length
      Returns:
        this - another

    - #### in

          @NotNull
          public PhysicalLength in(@NotNull
                                            LengthUnit targetUnit)

      Get this length in another unit.
      Parameters:
        `targetUnit` - other unit
      Returns:
        physical length in the given unit

    - #### compareTo

          public int compareTo(@NotNull
                               PhysicalLength o)

      Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

      The implementor must ensure `sgn(x.compareTo(y)) == -sgn(y.compareTo(x))` for all `x` and `y`. (This implies that `x.compareTo(y)` must throw an exception iff `y.compareTo(x)` throws an exception.)

      The implementor must also ensure that the relation is transitive: `(x.compareTo(y)>0 && y.compareTo(z)>0)` implies `x.compareTo(z)>0`.

      Finally, the implementor must ensure that `x.compareTo(y)==0` implies that `sgn(x.compareTo(z)) == sgn(y.compareTo(z))`, for all `z`.

      It is strongly recommended, but not strictly required that `(x.compareTo(y)==0) == (x.equals(y))`. Generally speaking, any class that implements the `Comparable` interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."

      In the foregoing description, the notation `sgn(`expression`)` designates the mathematical signum function, which is defined to return one of `-1`, `0`, or `1` according to whether the value of expression is negative, zero or positive.

      Specified by:
        `compareTo` in interface `java.lang.Comparable<PhysicalLength>`
      Parameters:
        `o` - the object to be compared.
      Returns:
        a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
      Throws:
        `java.lang.NullPointerException` - if the specified object is null
        `java.lang.ClassCastException` - if the specified object's type prevents it from being compared to this object.

    - #### fromString

          @NotNull
          public static PhysicalLength fromString(@NotNull
                                                           java.lang.String descr,
                                                           @Nullable
                                                           java.util.Locale locale)
                                                    throws IllegalPhysicalLengthFormatException

      Decodes a physical length description in text form. E.g. "12 km", "-7.3in" and similar.
      Parameters:
        `descr` - text description containing a physical length
        `locale` - locale to use for number decoding
      Returns:
        a physical length
      Throws:
        `IllegalPhysicalLengthFormatException` - if the string does not contain a valid physical length
        `java.lang.NullPointerException` - if descr is `null`

    - #### fromString

          @NotNull
          public static PhysicalLength fromString(@NotNull
                                                           java.lang.String descr)
                                                    throws IllegalPhysicalLengthFormatException

      Decodes a physical length description in text form,using the default locale. E.g. "12 km", "-7.3in" and similar.
      Parameters:
        `descr` - text description containing a physical length
      Returns:
        a physical length
      Throws:
        `IllegalPhysicalLengthFormatException` - if the string does not contain a valid physical length
        `java.lang.NullPointerException` - if descr is `null`

    - #### in

          @NotNull
          public static PhysicalLength in(double inches)

      Factory method for lengths in inches.
      Parameters:
        `inches` - number of inches
      Returns:
        length with the given number of inches

    - #### ft

          @NotNull
          public static PhysicalLength ft(double feet)

      Factory method for lengths in foot.
      Parameters:
        `feet` - number of feet
      Returns:
        length with the given number of feet

    - #### m

          @NotNull
          public static PhysicalLength m(double meter)

      Factory method for lengths in meter.
      Parameters:
        `meter` - number of meters
      Returns:
        length with the given number of meters

    - #### mm

          @NotNull
          public static PhysicalLength mm(double millimeter)

      Factory method for lengths in millimeter.
      Parameters:
        `millimeter` - number of millimeters
      Returns:
        length with the given number of millimeters

    - #### main

          public static void main(java.lang.String[] args)