## org.das2.datum.Units

Class for indicating physical units, and other random units.

## dimensionless

## radians

## degrees

## deg

## degrees2

## rgbColor

It's often enough that we just want to paint data with a particular color that there's a special unit which is used to trigger a branch, and the color will be used. This can have an alpha channel as well in the high byte, but zero will imply that the alpha channel is missing and opaque will be used.

## celciusDegrees

## fahrenheitDegrees

## years

## days

## hours

## hours2

## minutes

## seconds

## seconds2

## milliseconds

## milliseconds2

## microseconds

## microseconds2

## microseconds3

## nanoseconds

## ns

## picoseconds

## bytesPerSecond

## kiloBytesPerSecond

## bytes

## kiloBytes

## hertz

## kiloHertz

## megaHertz

## gigaHertz

## eV

## keV

## MeV

## pcm3

1 / cm3

## kelvin

## cm_2s_1keV_1

## cm_2s_1MeV_1

## v2pm2Hz

Volts 2 m-2 Hz-1

## wpm2

Watts / m2

## meters

## millimeters

## centimeters

## kiloMeters

## inches

## typographicPoints

## nT

## cmps

## mps

## centigrade

begin of LocationUnits. These must be defined after the physical units to support Basis.

## fahrenheitScale

## dollars

currencies for demonstration purposes.

## euros

## yen

## rupee

## us2020

Microseconds since midnight Jan 1, 2020, excluding those within a leap second. Differences across leap second boundaries do not represent the number of microseconds elapsed.

## us2000

Microseconds since midnight Jan 1, 2000, excluding those within a leap second. Differences across leap second boundaries do not represent the number of microseconds elapsed.

## us1980

Microseconds since midnight Jan 1, 1980, excluding those within a leap second.

## t2010

Seconds since midnight Jan 1, 2010, excluding leap seconds.

## t2000

Seconds since midnight Jan 1, 2000, excluding leap seconds.

## t1970

seconds since midnight Jan 1, 1970, excluding leap seconds.

## ms1970

milliseconds since midnight Jan 1, 1970, excluding leap seconds.

## us1970

milliseconds since midnight Jan 1, 1970, excluding leap seconds.

## mj1958

roughly days since on midnight on 1958-01-01, Julian - 2436204.5 to be more precise.

## mjd

The Modified Julian Day (MJD) is the number of days (with decimal fraction of the day) that have elapsed since midnight at the beginning of Wednesday November 17, 1858. Julian - 2400000.5

## julianDay

The Julian Day (MJD) is the number of days (with decimal fraction of the day) that have elapsed since noon on January 1, 4713 BCE. Julian - 2400000.5

## cdfEpoch

cdf epoch milliseconds since midnight, 01-Jan-0000, excluding those with a leap second. There must be skipped days, because this doesn't yield 01-Jan-0000 for 0., but works fine at 1-1-2000., excluding those within a leap second

## cdfTT2000

the number of nanoseconds since 01-Jan-2000T12:00, roughly. This includes leap seconds, so conversion is more than a scale,offset.

## decimalYear

the year plus the fraction into the current year, ((doy-1)/365) for non-leap years.

## percent

ratiometric units

## dB

Define a set of units to describe ratiometric (logarithmic) spacing. Note the log10Ratio is the preferred method for expressing spacing, but all are convertible See logERatio, log10Ratio and Google for "fold change."

## ampRatio

## percentIncrease

## log10Ratio

## logERatio

## add

add( Number a, Number b, Units bUnits ) → Datum

### Parameters

a - a Number
b - a Number
bUnits - an Units

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## convertDoubleTo

convertDoubleTo( Units toUnits, double value ) → double

convert the double in this units' space to toUnits' space.

### Parameters

toUnits - the units.
value - the value in toUnits.

### Returns:

the double in the new units system.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## createDatum

createDatum( double value ) → Datum

### Parameters

value - a double

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]
createDatum( int value ) → Datum [view source]
createDatum( long value ) → Datum [view source]
createDatum( Number value ) → Datum [view source]

## createDatum

createDatum( Datum value ) → Datum

create a Datum with the units. For example,

- Units.cm.createDatum('5m') → '500cm'
- eu.createDatum(datum('voyager1')) will convert to the new ordinal units.

### Parameters

value - a Datum

### Returns:

a Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]
createDatum( double value, double resolution ) → Datum [view source]

## divide

divide( Number a, Number b, Units bUnits ) → Datum

### Parameters

a - a Number
b - a Number
bUnits - an Units

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( Datum datum ) → String

format the Datum.

### Parameters

datum - the Datum

### Returns:

the Datum formatted as a string.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getAllUnits

getAllUnits( ) → java.util.List

return all the known units.

### Returns:

list of all the known units.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getBasis

getBasis( ) → org.das2.datum.Basis

return the Basis which defines the meaning of zero and the direction of positive values, such as "since midnight, Jan 1, 1970"

### Returns:

the Basis object, which simply identifies a basis.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getByName

getByName( String s ) → Units

returns a Units object with the given string representation that is stored in the unitsMap. Unlike lookupUnits, this will not allocate new units but will throw an IllegalArgumentException if the string is not recognized.

### Parameters

s - units identifier

### Returns:

units object

### See Also:

lookupUnits(java.lang.String)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getCanonicalUnit

getCanonicalUnit( Units units ) → Units

return the preferred unit to use when there are multiple representations of the same unit (having conversion UnitsConverter.IDENTITY).

### Parameters

units - an Units

### Returns:

the preferred unit
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getConverter

getConverter( Units fromUnits, Units toUnits ) → org.das2.datum.UnitsConverter

lookup the UnitsConverter object that takes numbers from fromUnits to toUnits. This will chain together UnitsConverters registered via units.registerConverter.

### Parameters

fromUnits - units instance that is the source units.
toUnits - units instance that is the target units.

### Returns:

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

## getConverter

getConverter( Units toUnits ) → org.das2.datum.UnitsConverter

Get the converter that goes from this Unit to toUnits. E.g. Units.meters.getConverter(Units.centimeters) yields a converter that multiplies by 100.

### Parameters

toUnits - an Units

### Returns:

a converter from this unit to toUnits.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getConvertibleUnits

getConvertibleUnits( ) → Units[]

return the units to which this unit is convertible.

### Returns:

the units to which this unit is convertible.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDatumFormatterFactory

getDatumFormatterFactory( ) → org.das2.datum.format.DatumFormatterFactory

return the formatter factor for this Datum.

### Returns:

an org.das2.datum.format.DatumFormatterFactory
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getFillDatum

getFillDatum( ) → Datum

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getFillDouble

getFillDouble( ) → double

### Returns:

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

## getId

getId( ) → String

get the id uniquely identifying the units. Note the id may contain special tokens, like "since" for time locations.

### Returns:

the id.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getOffsetUnits

getOffsetUnits( ) → Units

return the units from the Basis for the unit, such as "seconds" in "seconds since midnight, Jan 1, 1970"

### Returns:

this units offsets.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## grannyFormat

grannyFormat( Datum datum ) → String

format the Datum, allowing use of subscripts and superscripts interpretted by GrannyTextRenderer.

### Parameters

datum - the Datum

### Returns:

the Datum formatted as a string, possibly containing control sequences like !A and !n, etc.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isConvertibleTo

isConvertibleTo( Units toUnits ) → boolean

return true if the unit can be converted to toUnits.

### Parameters

toUnits - Units object.

### Returns:

true if the unit can be converted to toUnits.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isFill

isFill( double value ) → boolean

### Parameters

value - a double

### Returns:

boolean
[search for examples] [view on GitHub] [view on old javadoc] [view source]
isFill( Number value ) → boolean [view source]

## isValid

isValid( double value ) → boolean

test if the double represents a valid datum in the context of this unit. Note slight differences in implementation may cause isFill and isValid to produce inconsistent results. For example, this code checks for NaNs whereas isFill does not.

### Parameters

value - the value to check.

### Returns:

true if the data is not fill and not NaN.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## lookupTimeLengthUnit

lookupTimeLengthUnit( String s ) → Units

return canonical das2 unit for colloquial time.

### Parameters

s - string containing time unit like s, sec, millisec, etc.

### Returns:

the unit or ParseException if the unit is not recognized.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## lookupTimeUnits

lookupTimeUnits( Datum base, Units offsetUnits ) → Units

lookupUnits canonical units object, or allocate one. If one is allocated, then parse for "<unit> since <datum>" and add conversion to "microseconds since 2000-001T00:00." Note leap seconds are ignored!

### Parameters

base - the base time, for example 2000-001T00:00.
offsetUnits - the offset units for example microseconds. Positive values of the units will be since the base time.

### Returns:

the unit.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## lookupTimeUnits

lookupTimeUnits( String units ) → Units

lookupUnits canonical units object, or allocate one. If one is allocated, then parse for "<unit> since <datum>" and add conversion to "microseconds since 2000-001T00:00" (us2000). Note leap seconds are ignored in the returned units, so each day is 86400 seconds long, and differences in times should not include leap seconds. Note this contains a few kludges as this for datasets encountered by Autoplot.

### Parameters

units - string like "microseconds since 2000-001T00:00" which will be the id.

### Returns:

a units object that implements.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## lookupUnits

lookupUnits( String sunits ) → Units

lookupUnits canonical units object, or allocate one if the unit has not been used already. Examples include: "nT" where it's already allocated, "apples" where it allocates a new one, and "seconds since 2011-12-21T00:00" where it uses lookupTimeUnits.

### Parameters

sunits - string identifier.

### Returns:

canonical units object.

### See Also:

getByName(java.lang.String)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## main

main( String[] args ) → void

### Parameters

args - a java.lang.String[]

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## multiply

multiply( Number a, Number b, Units bUnits ) → Datum

### Parameters

a - a Number
b - a Number
bUnits - an Units

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## nominal

nominal( ) → org.das2.datum.EnumerationUnits

return unit for identifying nominal data. Strings are enumerated using this unit using the result's create(string) method, which returns a datum representing the string. This method allocates a number for the string if one hasn't already been allocated, and the name is unique within the namespace "default".

### Returns:

an EnumerationUnit with the namespace "default"
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## nominal

nominal( String nameSpace ) → org.das2.datum.EnumerationUnits

return unit for identifying nominal data. Strings are enumerated using this unit using the result's create(string) method, which returns a datum representing the string. This method allocates a number for the string if one hasn't already been allocated, and the name is unique within the namespace named.

### Parameters

nameSpace - a String

### Returns:

an EnumerationUnit.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( String s ) → Datum

parse the string in the context of these units. The string may throw a parse exception if it cannot be parsed, or may return a known unit.

### Parameters

s - a String

### Returns:

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

## registerConverter

registerConverter( Units toUnits, org.das2.datum.UnitsConverter converter ) → void

register a converter between the units. Note these converters can be changed together to derive conversions. (A to B, B to C defines A to C.)

### Parameters

toUnits - the target units
converter - the converter that goes from this unit to target units.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## subtract

subtract( Number a, Number b, Units bUnits ) → Datum

### Parameters

a - a Number
b - a Number
bUnits - an Units

### Returns:

org.das2.datum.Datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toString

toString( ) → String

### Returns:

java.lang.String
[search for examples] [view on GitHub] [view on old javadoc] [view source]