org.das2.datum
Class Datum

java.lang.Object
  extended by org.das2.datum.Datum
All Implemented Interfaces:
java.lang.Comparable
Direct Known Subclasses:
Datum.Double

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

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 itsself 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.


Nested Class Summary
static class Datum.Double
          class backing Datums with a double.
 
Method Summary
 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 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 indentified 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 isValid()
          Deprecated. Use isFinite instead, or getValue.
 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 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 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()
 
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.

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 propogate errors through the calculation.

Parameters:
units - the Units in which the double resolution should be returned. Note the units must be convertable 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 indentified 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.

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 convertable 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 convertable 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 convertable to this Datum's units.
Returns:
true if this is less than a.
Throws:
java.lang.IllegalArgumentException - if the two don't have convertable units.

gt

public boolean gt(Datum a)
           throws java.lang.IllegalArgumentException
returns true if this is greater than a.

Parameters:
a - a datum convertable to this Datum's units.
Returns:
true if this is greater than a.
Throws:
java.lang.IllegalArgumentException - if the two don't have convertable 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 convertable 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 convertable 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 convertable 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 convertable 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 convertable 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 convertable to this Datum's units.

isValid

public boolean isValid()
Deprecated. Use isFinite instead, or getValue.

returns true if the value is non NaN.

Returns:
true if the value is non NaN.

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 interpretted 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 interpretted 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.