org.das2.datum
Class Datum

java.lang.Object
  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.