org.das2.datum.Datum

A Datum is a number in the context of a Unit, for example "15 microseconds." A Datum object has methods for

Also a Datum's precision can be limited to improve formatting.

abs

abs( ) → Datum

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:

a Datum

See Also:

value() which returns the double value.


[search for examples] [view on GitHub] [view on old javadoc] [view source]

add

add( Datum 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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

add

add( Number value, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

add

add( double d, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

compareTo

compareTo( Object a ) → int

compare the datum to the object.

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

compareTo

compareTo( Datum a ) → int

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

convertTo

convertTo( Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( double value ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( double value, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( double value, Units units, org.das2.datum.format.DatumFormatter formatter ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( double value, Units units, double resolution ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( double value, Units units, double resolution, org.das2.datum.format.DatumFormatter formatter ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( long value ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( long value, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( long value, Units units, org.das2.datum.format.DatumFormatter formatter ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( int value ) → Datum

creates a dimensionless datum backed by an int.

Parameters

value - the magnitude of the dimensionless datum.

Returns:

a dimensionless Datum with the given value.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

create

create( int value, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

div

div( Datum 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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

divide

divide( Datum a ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

divide

divide( Number a, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

divide

divide( double d ) → Datum

divide this by the dimensionless double.

Parameters

d - the magnitude of the divisor.

Returns:

the quotient.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

doubleValue

doubleValue( Units units ) → double

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

equals

equals( Object a ) → boolean

returns true if the two datums are equal. That is, their double values are equal when converted to the same units.

Parameters

a - the Object to compare to.

Returns:

true if the datums are equal.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

equals

equals( Datum a ) → boolean

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

exp10

exp10( ) → Datum

return Math.pow(10,v)

Returns:

Math.pow(10,v)

[search for examples] [view on GitHub] [view on old javadoc] [view source]

ge

ge( Datum a ) → boolean

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 {@code a}.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

getFormatter

getFormatter( ) → org.das2.datum.format.DatumFormatter

returns a formatter suitable for formatting this datum as a string.

Returns:

a formatter to be used to format this Datum into a String.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

getResolution

getResolution( Units units ) → double

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

getUnits

getUnits( ) → Units

returns the datum's units. For example, UT times might have the units Units.us2000.

Returns:

the datum's units.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

gt

gt( Datum a ) → boolean

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 {@code a}.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

hashCode

hashCode( ) → int

returns a hashcode that is a function of the value and the units.

Returns:

a hashcode for the datum

[search for examples] [view on GitHub] [view on old javadoc] [view source]

intValue

intValue( Units units ) → int

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

isFill

isFill( ) → boolean

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

isFinite

isFinite( ) → boolean

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

le

le( Datum a ) → boolean

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 {@code a}.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

log10

log10( ) → Datum

return log10 of this datum.

Returns:

log10 of this datum.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

lt

lt( Datum a ) → boolean

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 {@code a}.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

minus

minus( Datum 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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

multiply

multiply( Datum a ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

multiply

multiply( Number a, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

multiply

multiply( double d ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

negative

negative( ) → Datum

Groovy scripting language uses this negation operator.

Returns:

a Datum such that it plus this is 0.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

plus

plus( Datum 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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

positive

positive( ) → Datum

Groovy scripting language uses this positive operator.

Returns:

this datum.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

power

power( double b ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

power

power( Datum 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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

subtract

subtract( Datum 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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

subtract

subtract( Number a, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

subtract

subtract( double d, Units units ) → Datum

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.

[search for examples] [view on GitHub] [view on old javadoc] [view source]

toString

toString( ) → String

returns a human readable String representation of the Datum, which should also be parseable with Units.parse()

Returns:

a human readable String representation of the Datum, which should also be parseable with Units.parse()

[search for examples] [view on GitHub] [view on old javadoc] [view source]

value

value( ) → double

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:

a double

[search for examples] [view on GitHub] [view on old javadoc] [view source]