Datum

java.lang.Object
- org.das2.datum.Datum

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

Direct Known Subclasses:

Datum.Double
```
public class Datum
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable
```
A Datum is a number in the context of a Unit, for example "15 microseconds." A Datum object has methods for formatting itself as a String, representing itself as a double in the context of another Unit, and mathematical operators that allow simple calculations to be made at the physical quantities. Also a Datum's precision can be limited to improve formatting.

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Datum.Double
class backing Datums with a double.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Datum.Double` class backing Datums with a double.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Datum`	`abs()` return the absolute value (magnitude) of this Datum.
`Datum`	`add(Datum datum)` returns a Datum whose value is the sum of `this` and `datum`, in `this.getUnits()`.
`Datum`	`add(double d, Units units)` returns a Datum whose value is the sum of `this` and value in the context of `units`, in `this.getUnits()`.
`Datum`	`add(java.lang.Number value, Units units)` returns a Datum whose value is the sum of `this` and value in the context of `units`, in `this.getUnits()`.
`int`	`compareTo(Datum a)` compare this to another datum.
`int`	`compareTo(java.lang.Object a)` compare the datum to the object.
`Datum`	`convertTo(Units units)` creates an equivalent datum using a different unit.
`static Datum`	`create(double value)` convenient method for creating a dimensionless Datum with the given value.
`static Datum`	`create(double value, Units units)` creates a datum with the given units and value, for example, `Datum.create( 54, Units.milliseconds )`
`static Datum`	`create(double value, Units units, DatumFormatter formatter)` Returns a Datum with a specific DatumFormatter attached to it.
`static Datum`	`create(double value, Units units, double resolution)` Returns a Datum with the given value and limited to the given resolution.
`static Datum`	`create(double value, Units units, double resolution, DatumFormatter formatter)` Returns a Datum with the given value and limited to the given resolution.
`static Datum`	`create(int value)` creates a dimensionless datum backed by an int.
`static Datum`	`create(int value, Units units)` creates a datum backed by an int with the given units.
`Datum`	`div(Datum datum)` Groovy scripting language uses this for overloading.
`Datum`	`divide(Datum a)` divide this by the datum `a`.
`Datum`	`divide(double d)` divide this by the dimensionless double.
`Datum`	`divide(java.lang.Number a, Units units)` divide this by the Number provided in the context of units.
`protected double`	`doubleValue()` returns the datum's double value.
`double`	`doubleValue(Units units)` returns a double representing the datum in the context of `units`.
`boolean`	`equals(Datum a)` returns true if the two datums are equal.
`boolean`	`equals(java.lang.Object a)` returns true if the two datums are equal.
`boolean`	`ge(Datum a)` returns true if this is greater than or equal to `a`.
`DatumFormatter`	`getFormatter()` returns a formatter suitable for formatting this datum as a string.
`double`	`getResolution(Units units)` returns the resolution (or precision) of the datum.
`Units`	`getUnits()` returns the datum's units.
`protected java.lang.Number`	`getValue()` returns the Number representing the datum's location in the space identified by its units.
`boolean`	`gt(Datum a)` returns true if this is greater than `a`.
`int`	`hashCode()` returns a hashcode that is a function of the value and the units.
`protected int`	`intValue()` returns the datum's int value.
`int`	`intValue(Units units)` returns a int representing the datum in the context of `units`.
`boolean`	`isFill()` convenience method for checking to see if a datum is a fill datum.
`boolean`	`isFinite()` returns true if the value is finite, that is not INFINITY or NaN.
`boolean`	`le(Datum a)` returns true if this is less than or equal to `a`.
`boolean`	`lt(Datum a)` returns true if this is less than `a`.
`Datum`	`minus(Datum datum)` Groovy scripting language uses this for overloading.
`Datum`	`multiply(Datum a)` multiply this by the datum `a`.
`Datum`	`multiply(double d)` multiply by a dimensionless number.
`Datum`	`multiply(java.lang.Number a, Units units)` multiply this by the Number provided in the context of units.
`Datum`	`negative()` Groovy scripting language uses this negation operator.
`Datum`	`plus(Datum datum)` Groovy scripting language uses this for overloading.
`Datum`	`positive()` Groovy scripting language uses this positive operator.
`Datum`	`power(Datum datum)` Groovy scripting language uses this for overloading a**b.
`Datum`	`power(double b)` Groovy scripting language uses this for overloading a**b.
`Datum`	`subtract(Datum datum)` returns a Datum whose value is the difference of `this` and `value`.
`Datum`	`subtract(double d, Units units)` returns a Datum whose value is the difference of `this` and value in the context of `units`.
`Datum`	`subtract(java.lang.Number a, Units units)` returns a Datum whose value is the difference of `this` and value in the context of `units`.
`java.lang.String`	`toString()` returns a human readable String representation of the Datum, which should also be parseable with Units.parse()
`double`	`value()` returns the double value without the unit, as long as the Units indicate this is a ratio measurement, and there is a meaningful 0.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - doubleValue
```
protected double doubleValue()
```
    returns the datum's double value. This protected method allows subclasses and classes within the package to peek at the double value.
    
    Returns:
    
    the double value of the datum in the context of its units.
  - doubleValue
```
public double doubleValue(Units units)
```
    returns a double representing the datum in the context of units.
    
    Parameters:
    
    units - the Units in which the double should be returned
    
    Returns:
    
    a double in the context of the provided units.
  - value
```
public double value()
```
    returns the double value without the unit, as long as the Units indicate this is a ratio measurement, and there is a meaningful 0. For example "5 Kg" → 5, but "2012-02-16T00:00" would throw an IllegalArgumentException. Note this was introduced because often we just need to check to see if a value is zero.
    
    Returns:
  - abs
```
public Datum abs()
```
    return the absolute value (magnitude) of this Datum. If this datum is fill then the result is fill. This will have the same units as the datum.
    
    Returns:
    
    Throws:
    
    java.lang.IllegalArgumentException - if the datum is not a ratio measurement (like a timetag).
    
    See Also:
    
    which returns the double value.
  - getResolution
```
public double getResolution(Units units)
```
    returns the resolution (or precision) of the datum. This is metadata for the datum, used primarily to limit the number of decimal places displayed in a string representation, but operators like add and multiply will propagate errors through the calculation.
    
    Parameters:
    
    units - the Units in which the double resolution should be returned. Note the units must be convertible to this.getUnits().getOffsetUnits().
    
    Returns:
    
    the double resolution of the datum in the context of units.
  - intValue
```
protected int intValue()
```
    returns the datum's int value. This protected method allows subclasses and classes within the package to peek at the value as an integer. (The intent was that a Datum might be backed by an integer instead of a double, so that numerical round-off issues can be avoided.)
    
    Returns:
    
    the integer value of the datum in the context of its units.
  - intValue
```
public int intValue(Units units)
```
    returns a int representing the datum in the context of units.
    
    Parameters:
    
    units - the Units in which the int should be returned
    
    Returns:
    
    a double in the context of the provided units.
  - getUnits
```
public Units getUnits()
```
    returns the datum's units. For example, UT times might have the units Units.us2000.
    
    Returns:
    
    the datum's units.
  - getValue
```
protected java.lang.Number getValue()
```
    returns the Number representing the datum's location in the space identified by its units. This protected method allows subclasses and classes within the package to peek at the value. (The intent was that a Datum might be backed by an integer, float, or double, depending on the application.)
    
    Returns:
    
    a Number in the context of the provided units.
  - isFill
```
public boolean isFill()
```
    convenience method for checking to see if a datum is a fill datum.
    
    Returns:
    
    true if the value is fill as defined by the Datum's units.
  - plus
```
public Datum plus(Datum datum)
```
    Groovy scripting language uses this for overloading.
    
    Parameters:
    
    datum - Datum to add, that is convertible to this.getUnits().
    
    Returns:
    
    a Datum that is the sum of the two values in this Datum's units.
  - minus
```
public Datum minus(Datum datum)
```
    Groovy scripting language uses this for overloading.
    
    Parameters:
    
    datum - Datum to subtract, that is convertible to this.getUnits().
    
    Returns:
    
    a Datum that is the sum of the two values in this Datum's units.
  - div
```
public Datum div(Datum datum)
```
    Groovy scripting language uses this for overloading.
    
    Parameters:
    
    datum - Datum to divide, that is convertible to this.getUnits().
    
    Returns:
    
    a Datum that is the divide of the two values in this Datum's units.
  - power
```
public Datum power(double b)
```
    Groovy scripting language uses this for overloading a**b.
    
    Parameters:
    
    b - double to exponentiate, that is dimensionless.
    
    Returns:
    
    a Datum that is the exponentiate of the two values in this Datum's units.
  - power
```
public Datum power(Datum datum)
```
    Groovy scripting language uses this for overloading a**b.
    
    Parameters:
    
    datum - Datum to exponentiate, that is dimensionless.
    
    Returns:
    
    a Datum that is the sum of the two values in this Datum's units.
  - negative
```
public Datum negative()
```
    Groovy scripting language uses this negation operator.
    
    Returns:
    
    a Datum such that it plus this is 0.
    
    Throws:
    
    java.lang.IllegalArgumentException - when the units are location units.
  - positive
```
public Datum positive()
```
    Groovy scripting language uses this positive operator.
    
    Returns:
    
    this datum.
  - add
```
public Datum add(Datum datum)
```
    returns a Datum whose value is the sum of this and datum, in this.getUnits().
    
    Parameters:
    
    datum - Datum to add, that is convertible to this.getUnits().
    
    Returns:
    
    a Datum that is the sum of the two values in this Datum's units.
  - add
```
public Datum add(java.lang.Number value,
                 Units units)
```
    returns a Datum whose value is the sum of this and value in the context of units, in this.getUnits().
    
    Parameters:
    
    value - a Number to add in the context of units.
    
    units - units defining the context of value. There should be a converter from units to this Datum's units.
    
    Returns:
    
    value Datum that is the sum of the two values in this Datum's units.
  - add
```
public Datum add(double d,
                 Units units)
```
    returns a Datum whose value is the sum of this and value in the context of units, in this.getUnits().
    
    Parameters:
    
    d - a Number to add in the context of units.
    
    units - units defining the context of value. There should be a converter from units to this Datum's units.
    
    Returns:
    
    value Datum that is the sum of the two values in this Datum's units.
  - subtract
```
public Datum subtract(Datum datum)
```
    returns a Datum whose value is the difference of this and value. The returned Datum will have units according to the type of units subtracted. For example, "1979-01-02T00:00" - "1979-01-01T00:00" = "24 hours" (this datum's unit's offset units), while "1979-01-02T00:00" - "1 hour" = "1979-01-01T23:00" (this datum's units.) Note also the resolution of the result is calculated.
    
    Parameters:
    
    datum - Datum to add, that is convertible to this.getUnits() or offset units.
    
    Returns:
    
    a Datum that is the sum of the two values in this Datum's units.
  - subtract
```
public Datum subtract(java.lang.Number a,
                      Units units)
```
    returns a Datum whose value is the difference of this and value in the context of units. The returned Datum will have units according to the type of units subtracted. For example, "1979-01-02T00:00" - "1979-01-01T00:00" = "24 hours" (this datum's unit's offset units), while "1979-01-02T00:00" - "1 hour" = "1979-01-01T23:00" (this datum's units.)
    
    Parameters:
    
    a - a Number to add in the context of units.
    
    units - units defining the context of value. There should be a converter from units to this Datum's units or offset units.
    
    Returns:
    
    value Datum that is the difference of the two values in this Datum's units.
  - subtract
```
public Datum subtract(double d,
                      Units units)
```
    returns a Datum whose value is the difference of this and value in the context of units. The returned Datum will have units according to the type of units subtracted. For example, "1979-01-02T00:00" - "1979-01-01T00:00" = "24 hours" (this datum's unit's offset units), while "1979-01-02T00:00" - "1 hour" = "1979-01-01T23:00" (this datum's units.)
    
    Parameters:
    
    d - a Number to add in the context of units.
    
    units - units defining the context of value. There should be a converter from units to this Datum's units or offset units.
    
    Returns:
    
    value Datum that is the difference of the two values in this Datum's units.
  - divide
```
public Datum divide(Datum a)
```
    divide this by the datum a. Currently, only division is only supported:
```
   between convertable units, resulting in a Units.dimensionless quantity, or
   by a Units.dimensionless quantity, and a datum with this datum's units is returned.
```
    This may change, as a generic SI units class is planned.
    Parameters:
    
    a - the datum divisor.
    
    Returns:
    
    the quotient.
  - divide
```
public Datum divide(java.lang.Number a,
                    Units units)
```
    divide this by the Number provided in the context of units. Currently, only division is only supported:
```
   between convertable units, resulting in a Units.dimensionless quantity, or
   by a Units.dimensionless quantity, and a datum with this datum's units is returned.
```
    This may change, as a generic SI units class is planned.
    Parameters:
    
    a - the magnitude of the divisor.
    
    units - the units of the divisor.
    
    Returns:
    
    the quotient.
  - divide
```
public Datum divide(double d)
```
    divide this by the dimensionless double.
    
    Parameters:
    
    d - the magnitude of the divisor.
    
    Returns:
    
    the quotient.
  - multiply
```
public Datum multiply(Datum a)
```
    multiply this by the datum a. Currently, only multiplication is only supported by a dimensionless datum, or when this is dimensionless. This may change, as a generic SI units class is planned. This should also throw an IllegalArgumentException if the units are LocationUnits (e.g. UT time), but doesn't. This may change.
    
    Parameters:
    
    a - the datum to multiply
    
    Returns:
    
    the product.
  - multiply
```
public Datum multiply(java.lang.Number a,
                      Units units)
```
    multiply this by the Number provided in the context of units. Currently, only multiplication is only supported by a dimensionless datum, or when this is dimensionless. This may change, as a generic SI units class is planned. This should also throw an IllegalArgumentException if the units are LocationUnits (e.g. UT time), but doesn't. This may change.
    
    Parameters:
    
    a - the magnitude of the multiplier.
    
    units - the units of the multiplier.
    
    Returns:
    
    the product.
  - multiply
```
public Datum multiply(double d)
```
    multiply by a dimensionless number. This should also throw an IllegalArgumentException if the units are LocationUnits (e.g. UT time), but doesn't. This may change.
    
    Parameters:
    
    d - the multiplier.
    
    Returns:
    
    the product.
  - convertTo
```
public Datum convertTo(Units units)
                throws java.lang.IllegalArgumentException
```
    creates an equivalent datum using a different unit. For example,x= Datum.create( 5, Units.seconds ); System.err.println( x.convertTo( Units.seconds ) );
    
    Parameters:
    
    units - the new Datum's units
    
    Returns:
    
    a datum with the new units, that is equal to the original datum.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the datum cannot be converted to the given units.
  - hashCode
```
public int hashCode()
```
    returns a hashcode that is a function of the value and the units.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hashcode for the datum
  - equals
```
public boolean equals(java.lang.Object a)
               throws java.lang.IllegalArgumentException
```
    returns true if the two datums are equal. That is, their double values are equal when converted to the same units.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    a - the Object to compare to.
    
    Returns:
    
    true if the datums are equal.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the Object is not a datum or the units are not convertable.
  - equals
```
public boolean equals(Datum a)
               throws java.lang.IllegalArgumentException
```
    returns true if the two datums are equal. That is, their double values are equal when converted to the same units.
    
    Parameters:
    
    a - the datum to compare
    
    Returns:
    
    true if the datums are equal.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the units are not convertable.
  - lt
```
public boolean lt(Datum a)
           throws java.lang.IllegalArgumentException
```
    returns true if this is less than a.
    
    Parameters:
    
    a - a datum convertible to this Datum's units.
    
    Returns:
    
    true if this is less than a.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the two don't have convertible units.
  - gt
```
public boolean gt(Datum a)
           throws java.lang.IllegalArgumentException
```
    returns true if this is greater than a.
    
    Parameters:
    
    a - a datum convertible to this Datum's units.
    
    Returns:
    
    true if this is greater than a.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the two don't have convertible units.
  - le
```
public boolean le(Datum a)
           throws java.lang.IllegalArgumentException
```
    returns true if this is less than or equal to a.
    
    Parameters:
    
    a - a datum convertible to this Datum's units.
    
    Returns:
    
    true if this is less than or equal to a.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the two don't have convertible units.
  - ge
```
public boolean ge(Datum a)
           throws java.lang.IllegalArgumentException
```
    returns true if this is greater than or equal to a.
    
    Parameters:
    
    a - a datum convertible to this Datum's units.
    
    Returns:
    
    true if this is greater than or equal to a.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the two don't have convertible units.
  - compareTo
```
public int compareTo(java.lang.Object a)
              throws java.lang.IllegalArgumentException
```
    compare the datum to the object.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable
    
    Parameters:
    
    a - the Object to compare this datum to.
    
    Returns:
    
    an int < 0 if this comes before Datum a in this Datum's units space, 0 if they are equal, and > 0 otherwise.
    
    Throws:
    
    java.lang.IllegalArgumentException - if a is not a Datum or is not convertible to this Datum's units.
  - compareTo
```
public int compareTo(Datum a)
              throws java.lang.IllegalArgumentException
```
    compare this to another datum.
    
    Parameters:
    
    a - the Datum to compare this datum to.
    
    Returns:
    
    an int < 0 if this comes before Datum a in this Datum's units space, 0 if they are equal, and > 0 otherwise.
    
    Throws:
    
    java.lang.IllegalArgumentException - if a is not convertible to this Datum's units.
  - isFinite
```
public boolean isFinite()
```
    returns true if the value is finite, that is not INFINITY or NaN.
    
    Returns:
    
    true if the value is finite, that is not INFINITY or NaN.
  - toString
```
public java.lang.String toString()
```
    returns a human readable String representation of the Datum, which should also be parseable with Units.parse()
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a human readable String representation of the Datum, which should also be parseable with Units.parse()
  - create
```
public static Datum create(double value)
```
    convenient method for creating a dimensionless Datum with the given value.
    
    Parameters:
    
    value - the magnitude of the datum.
    
    Returns:
    
    a dimensionless Datum with the given value.
  - create
```
public static Datum create(double value,
                           Units units)
```
    creates a datum with the given units and value, for example, Datum.create( 54, Units.milliseconds )
    
    Parameters:
    
    value - the magnitude of the datum.
    
    units - the units of the datum.
    
    Returns:
    
    a Datum with the given units and value.
  - create
```
public static Datum create(double value,
                           Units units,
                           DatumFormatter formatter)
```
    Returns a Datum with a specific DatumFormatter attached to it. This was was used to limit resolution before limited resolution Datums were introduced.
    
    Parameters:
    
    value - the magnitude of the datum.
    
    units - the units of the datum.
    
    formatter - the DatumFormatter that should be used to format this datum, which will be returned by getFormatter().
    
    Returns:
    
    a Datum with the given units and value, that should return the given formatter when asked.
  - create
```
public static Datum create(double value,
                           Units units,
                           double resolution)
```
    Returns a Datum with the given value and limited to the given resolution. When formatted, the formatter should use this resolution to limit the precision displayed.
    
    Parameters:
    
    value - the magnitude of the datum, or value to be interpreted in the context of units.
    
    units - the units of the datum.
    
    resolution - the limit to which the datum's precision is known.
    
    Returns:
    
    a Datum with the given units and value.
  - create
```
public static Datum create(double value,
                           Units units,
                           double resolution,
                           DatumFormatter formatter)
```
    Returns a Datum with the given value and limited to the given resolution. When formatted, the formatter should use this resolution to limit the precision displayed.
    
    Parameters:
    
    value - the magnitude of the datum, or value to be interpreted in the context of units.
    
    units - the units of the datum.
    
    resolution - the limit to which the datum's precision is known.
    
    formatter - the DatumFormatter that should be used to format this datum, which will be returned by getFormatter().
    
    Returns:
    
    a Datum with the given units and value.
  - create
```
public static Datum create(int value)
```
    creates a dimensionless datum backed by an int.
    
    Parameters:
    
    value - the magnitude of the dimensionless datum.
    
    Returns:
    
    a dimensionless Datum with the given value.
  - create
```
public static Datum create(int value,
                           Units units)
```
    creates a datum backed by an int with the given units.
    
    Parameters:
    
    value - the magnitude of the datum
    
    units - the units of the datum
    
    Returns:
    
    a Datum with the given units and value.
  - getFormatter
```
public DatumFormatter getFormatter()
```
    returns a formatter suitable for formatting this datum as a string.
    
    Returns:
    
    a formatter to be used to format this Datum into a String.

Class Datum

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

doubleValue

doubleValue

value

abs

getResolution

intValue

intValue

getUnits

getValue

isFill

plus

minus

div

power

power

negative

positive

add

add

add

subtract

subtract

subtract

divide

divide

divide

multiply

multiply

multiply

convertTo

hashCode

equals

equals

lt

gt

le

ge

compareTo

compareTo

isFinite

toString

create

create

create

create

create

create

create

getFormatter