Measurement
Date: 2016-06-25

org.osgi.util.measurement

## Class Measurement

- java.lang.Object
- - org.osgi.util.measurement.Measurement

- All Implemented Interfaces:
    java.lang.Comparable

      public class Measurement
      extends java.lang.Object
      implements java.lang.Comparable

  Represents a value with an error, a unit and a time-stamp.

  A `Measurement` object is used for maintaining the tuple of value, error, unit and time-stamp. The value and error are represented as doubles and the time is measured in milliseconds since midnight, January 1, 1970 UTC.

  Mathematic methods are provided that correctly calculate taking the error into account. A runtime error will occur when two measurements are used in an incompatible way. E.g., when a speed (m/s) is added to a distance (m). The measurement class will correctly track changes in unit during multiplication and division, always coercing the result to the most simple form. See `Unit` for more information on the supported units.

  Errors in the measurement class are absolute errors. Measurement errors should use the P95 rule. Actual values must fall in the range value +/- error 95% or more of the time.

  A `Measurement` object is immutable in order to be easily shared.

  Note: This class has a natural ordering that is inconsistent with equals. See `compareTo(Object)`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Measurement(double value)` Create a new `Measurement` object with an error of 0.0, a unit of `Unit.unity` and a time of zero.
    `Measurement(double value, double error, Unit unit)` Create a new `Measurement` object with a time of zero.
    `Measurement(double value, double error, Unit unit, long time)` Create a new `Measurement` object.
    `Measurement(double value, Unit unit)` Create a new `Measurement` object with an error of 0.0 and a time of zero.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Measurement` | `add(double d)` Returns a new `Measurement` object that is the sum of this object added to the specified value.
    `Measurement` | `add(double d, Unit u)` Returns a new `Measurement` object that is the sum of this object added to the specified value.
    `Measurement` | `add(Measurement m)` Returns a new `Measurement` object that is the sum of this object added to the specified object.
    `int` | `compareTo(java.lang.Object obj)` Compares this object with the specified object for order.
    `Measurement` | `div(double d)` Returns a new `Measurement` object that is the quotient of this object divided by the specified value.
    `Measurement` | `div(double d, Unit u)` Returns a new `Measurement` object that is the quotient of this object divided by the specified value.
    `Measurement` | `div(Measurement m)` Returns a new `Measurement` object that is the quotient of this object divided by the specified object.
    `boolean` | `equals(java.lang.Object obj)` Returns whether the specified object is equal to this object.
    `double` | `getError()` Returns the error of this `Measurement` object.
    `long` | `getTime()` Returns the time at which this `Measurement` object was taken.
    `Unit` | `getUnit()` Returns the `Unit` object of this `Measurement` object.
    `double` | `getValue()` Returns the value of this `Measurement` object.
    `int` | `hashCode()` Returns a hash code value for this object.
    `Measurement` | `mul(double d)` Returns a new `Measurement` object that is the product of this object multiplied by the specified value.
    `Measurement` | `mul(double d, Unit u)` Returns a new `Measurement` object that is the product of this object multiplied by the specified value.
    `Measurement` | `mul(Measurement m)` Returns a new `Measurement` object that is the product of this object multiplied by the specified object.
    `Measurement` | `sub(double d)` Returns a new `Measurement` object that is the subtraction of the specified value from this object.
    `Measurement` | `sub(double d, Unit u)` Returns a new `Measurement` object that is the subtraction of the specified value from this object.
    `Measurement` | `sub(Measurement m)` Returns a new `Measurement` object that is the subtraction of the specified object from this object.
    `java.lang.String` | `toString()` Returns a `String` object representing this `Measurement` object.

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

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

- - ### Constructor Detail

    - #### Measurement

          public Measurement(double value,
                     double error,
                     Unit unit,
                     long time)

      Create a new `Measurement` object.
      Parameters:
        `value` - The value of the `Measurement`.
        `error` - The error of the `Measurement`.
        `unit` - The `Unit` object in which the value is measured. If this argument is `null`, then the unit will be set to `Unit.unity`.
        `time` - The time measured in milliseconds since midnight, January 1, 1970 UTC.

    - #### Measurement

          public Measurement(double value,
                     double error,
                     Unit unit)

      Create a new `Measurement` object with a time of zero.
      Parameters:
        `value` - The value of the `Measurement`.
        `error` - The error of the `Measurement`.
        `unit` - The `Unit` object in which the value is measured. If this argument is `null`, then the unit will be set to `Unit.unity`.

    - #### Measurement

          public Measurement(double value,
                     Unit unit)

      Create a new `Measurement` object with an error of 0.0 and a time of zero.
      Parameters:
        `value` - The value of the `Measurement`.
        `unit` - The `Unit` in which the value is measured. If this argument is `null`, then the unit will be set to `Unit.unity`.

    - #### Measurement

          public Measurement(double value)

      Create a new `Measurement` object with an error of 0.0, a unit of `Unit.unity` and a time of zero.
      Parameters:
        `value` - The value of the `Measurement`.

  - ### Method Detail

    - #### getValue

          public final double getValue()

      Returns the value of this `Measurement` object.
      Returns:
        The value of this `Measurement` object as a double.

    - #### getError

          public final double getError()

      Returns the error of this `Measurement` object. The error is always a positive value.
      Returns:
        The error of this `Measurement` as a double.

    - #### getUnit

          public final Unit getUnit()

      Returns the `Unit` object of this `Measurement` object.
      Returns:
        The `Unit` object of this `Measurement` object.
      See Also:
        `Unit`

    - #### getTime

          public final long getTime()

      Returns the time at which this `Measurement` object was taken. The time is measured in milliseconds since midnight, January 1, 1970 UTC, or zero when not defined.
      Returns:
        The time at which this `Measurement` object was taken or zero.

    - #### mul

          public Measurement mul(Measurement m)

      Returns a new `Measurement` object that is the product of this object multiplied by the specified object.
      Parameters:
        `m` - The `Measurement` object that will be multiplied with this object.
      Returns:
        A new `Measurement` that is the product of this object multiplied by the specified object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified object cannot be multiplied.
      See Also:
        `Unit`

    - #### mul

          public Measurement mul(double d,
                        Unit u)

      Returns a new `Measurement` object that is the product of this object multiplied by the specified value.
      Parameters:
        `d` - The value that will be multiplied with this object.
        `u` - The `Unit` of the specified value.
      Returns:
        A new `Measurement` object that is the product of this object multiplied by the specified value. The error and unit of the new object are computed. The time of the new object is set to the time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the units of this object and the specified value cannot be multiplied.
      See Also:
        `Unit`

    - #### mul

          public Measurement mul(double d)

      Returns a new `Measurement` object that is the product of this object multiplied by the specified value.
      Parameters:
        `d` - The value that will be multiplied with this object.
      Returns:
        A new `Measurement` object that is the product of this object multiplied by the specified value. The error of the new object is computed. The unit and time of the new object is set to the unit and time of this object.

    - #### div

          public Measurement div(Measurement m)

      Returns a new `Measurement` object that is the quotient of this object divided by the specified object.
      Parameters:
        `m` - The `Measurement` object that will be the divisor of this object.
      Returns:
        A new `Measurement` object that is the quotient of this object divided by the specified object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified object cannot be divided.
      See Also:
        `Unit`

    - #### div

          public Measurement div(double d,
                        Unit u)

      Returns a new `Measurement` object that is the quotient of this object divided by the specified value.
      Parameters:
        `d` - The value that will be the divisor of this object.
        `u` - The `Unit` object of the specified value.
      Returns:
        A new `Measurement` that is the quotient of this object divided by the specified value. The error and unit of the new object are computed. The time of the new object is set to the time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified object cannot be divided.
      See Also:
        `Unit`

    - #### div

          public Measurement div(double d)

      Returns a new `Measurement` object that is the quotient of this object divided by the specified value.
      Parameters:
        `d` - The value that will be the divisor of this object.
      Returns:
        A new `Measurement` object that is the quotient of this object divided by the specified value. The error of the new object is computed. The unit and time of the new object is set to the `Unit` and time of this object.

    - #### add

          public Measurement add(Measurement m)

      Returns a new `Measurement` object that is the sum of this object added to the specified object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.
      Parameters:
        `m` - The `Measurement` object that will be added with this object.
      Returns:
        A new `Measurement` object that is the sum of this and m.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified object cannot be added.
      See Also:
        `Unit`

    - #### add

          public Measurement add(double d,
                        Unit u)

      Returns a new `Measurement` object that is the sum of this object added to the specified value.
      Parameters:
        `d` - The value that will be added with this object.
        `u` - The `Unit` object of the specified value.
      Returns:
        A new `Measurement` object that is the sum of this object added to the specified value. The unit of the new object is computed. The error and time of the new object is set to the error and time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified value cannot be added.
      See Also:
        `Unit`

    - #### add

          public Measurement add(double d)

      Returns a new `Measurement` object that is the sum of this object added to the specified value.
      Parameters:
        `d` - The value that will be added with this object.
      Returns:
        A new `Measurement` object that is the sum of this object added to the specified value. The error, unit, and time of the new object is set to the error, `Unit` and time of this object.

    - #### sub

          public Measurement sub(Measurement m)

      Returns a new `Measurement` object that is the subtraction of the specified object from this object.
      Parameters:
        `m` - The `Measurement` object that will be subtracted from this object.
      Returns:
        A new `Measurement` object that is the subtraction of the specified object from this object. The error and unit of the new object are computed. The time of the new object is set to the time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified object cannot be subtracted.
      See Also:
        `Unit`

    - #### sub

          public Measurement sub(double d,
                        Unit u)

      Returns a new `Measurement` object that is the subtraction of the specified value from this object.
      Parameters:
        `d` - The value that will be subtracted from this object.
        `u` - The `Unit` object of the specified value.
      Returns:
        A new `Measurement` object that is the subtraction of the specified value from this object. The unit of the new object is computed. The error and time of the new object is set to the error and time of this object.
      Throws:
        `java.lang.ArithmeticException` - If the `Unit` objects of this object and the specified object cannot be subtracted.
      See Also:
        `Unit`

    - #### sub

          public Measurement sub(double d)

      Returns a new `Measurement` object that is the subtraction of the specified value from this object.
      Parameters:
        `d` - The value that will be subtracted from this object.
      Returns:
        A new `Measurement` object that is the subtraction of the specified value from this object. The error, unit and time of the new object is set to the error, `Unit` object and time of this object.

    - #### toString

          public java.lang.String toString()

      Returns a `String` object representing this `Measurement` object.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a `String` object representing this `Measurement` object.

    - #### compareTo

          public int compareTo(java.lang.Object obj)

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

      Note: This class has a natural ordering that is inconsistent with equals. For this method, another `Measurement` object is considered equal if there is some `x` such that

           getValue() - getError() <= x <= getValue() + getError()

      for both `Measurement` objects being compared.
      Specified by:
        `compareTo` in interface `java.lang.Comparable`
      Parameters:
        `obj` - The object to be compared.
      Returns:
        A negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified object.
      Throws:
        `java.lang.ClassCastException` - If the specified object is not of type `Measurement`.
        `java.lang.ArithmeticException` - If the unit of the specified `Measurement` object is not equal to the `Unit` object of this object.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this object.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        A hash code value for this object.

    - #### equals

          public boolean equals(java.lang.Object obj)

      Returns whether the specified object is equal to this object. Two `Measurement` objects are equal if they have same value, error and `Unit`.

      Note: This class has a natural ordering that is inconsistent with equals. See `compareTo(Object)`.

      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - The object to compare with this object.
      Returns:
        `true` if this object is equal to the specified object; `false` otherwise.