## org.das2.datum.DatumUtil

## asOrderOneUnits

asOrderOneUnits( Datum d ) → Datum

This method takes the input datum and gets it as close to order one as possible by trying all possible conversions.

### Parameters

d - A datum that needs to have its units changed to order one units.

### Returns:

The order-one-ified Datum.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bestFormatter

bestFormatter( org.das2.datum.DatumVector datums ) → org.das2.datum.format.DatumFormatter

return the most efficient formatter for the datums, supporting nominal data, TimeLocationUnits, and LocationUnits, and other data.

### Parameters

datums - a DatumVector

### Returns:

a formatter for the set.

### See Also:

https://github.com/autoplot/dev/blob/master/demos/2021/20211203/testBestFormatter.jy
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bestFormatter

bestFormatter( org.das2.datum.DatumVector datums, DatumRange context ) → org.das2.datum.format.DatumFormatter

return the most efficient formatter for the datums, supporting nominal data, TimeLocationUnits, and LocationUnits, and other data. A context can be provided, for example when the title contains the date of the data and only $H:$M should be shown.

### Parameters

datums - a DatumVector
context - externally-represented context, or null if none is used.

### Returns:

a formatter for the set.

### See Also:

https://github.com/autoplot/dev/blob/master/demos/2021/20211203/testBestFormatter.jy
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bestFormatter

bestFormatter( Datum minimum, Datum maximum, int nsteps ) → org.das2.datum.format.DatumFormatter

return a DatumFormatter that efficiently formats evenly-spaced datums from minimum to maximum with nstep intervals. (Interval size is maximum.subtract(minimum).divide(nsteps))

### Parameters

minimum - a Datum
maximum - a Datum
nsteps - the number of sub intervals

### Returns:

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

## bestTimeFormatter

bestTimeFormatter( Datum minimum, Datum maximum, int nsteps ) → org.das2.datum.format.DatumFormatter

### Parameters

minimum - a Datum
maximum - a Datum
nsteps - an int

### Returns:

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

## createValid

createValid( String s ) → Datum

create a dimensionless datum by parsing the string. See TimeUtil.createValid( String stime ).

### Parameters

s - a String

### Returns:

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

## datumStringSplit

datumStringSplit( String s ) → String[]

splits the datum into a magnitude part and a unit part. When times are detected, "UTC" will be the units part. Here is a list to test against, and the motivation:

- 2014-05-29T00:00 ISO8601 times, cannot contain spaces.
- 5.e4 Hz registered known units
- 5.6 foos units from the wild
- 5.7 bytes/sec mix of MKS and units from the wild.
- 5.7Hz no space
- 5.7T no space, contains T.
- +5.7E+2Hz more challenging double.
- $57 unit before number

Note: units cannot start with E or e then a number or plus or minus. Datums cannot contain commas, semicolons, or quotes. NaN is Double.NaN. TODO: only $ is supported as a prefix. Others should be considered for completeness.

### Parameters

s - the string-formatted datum

### Returns:

the magnitude and the units, or [null,s] when it is not parseable.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## divp

divp( Datum amount, Datum delta ) → Datum

this is the divide that rounds down to the next integer, so divp("-25hr","24hr") is -2. Note that the result must be dimensionless, other forms are not supported. TODO: study inconsistencies with QDataset Ops divp

### Parameters

amount - a Datum
delta - a Datum

### Returns:

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

## doubleValues

doubleValues( Datum[] datums, Units units ) → double[]

### Parameters

datums - an org.das2.datum.Datum[]
units - an Units

### Returns:

double[]
[search for examples] [view on GitHub] [view on old javadoc] [view source]
doubleValues( Datum[] datums, Units[] unitsArray ) → double[] [view source]

## fractionalDigits

fractionalDigits( Datum resolution ) → int

### Parameters

resolution - a Datum

### Returns:

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

## limitLogResolutionFormatter

limitLogResolutionFormatter( Datum minimum, Datum maximum, int nsteps ) → org.das2.datum.format.DatumFormatter

### Parameters

minimum - a Datum
maximum - a Datum
nsteps - an int

### Returns:

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

## limitResolutionFormatter

limitResolutionFormatter( Datum minimum, Datum maximum, int nsteps ) → org.das2.datum.format.DatumFormatter

### Parameters

minimum - a Datum
maximum - a Datum
nsteps - an int

### Returns:

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

## lookupDatum

lookupDatum( String s ) → Datum

Attempts to resolve strings commonly encountered. This was introduced to create a standard method for resolving Strings in ASCII files to a Datum. This follows the rules that:

- Things that appear to be times are parsed to a TimeLocationUnit.
- a double followed by whitespace then a unit is parsed as lookupUnit then parse(double)

Here is a list to test against, and the motivation:

- 2014-05-29T00:00 ISO8601 times, cannot contain spaces.
- 5.e4 Hz registered known units
- 5.6 foos units from the wild
- 5.7 bytes/sec mix of MKS and units from the wild.
- 5.7Hz no space
- 5.7T no space, (contains T which is also in ISO8601 times)
- 5.7eggs e could be mistaken for exponent.
- +5.7E+2Hz more challenging double.
- $57 unit before number

### Parameters

s - a String

### Returns:

a Datum containing the value.

### See Also:

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

## modp

modp( Datum amount, Datum delta ) → Datum

return the modulo within the delta. The result will always be a positive number. For example:

modp('-3days','7days') | 4days
modp('10days','7days') | 3days

A typical use might be:

    %{code
     t= t + modp(t-phaseStart,span)
     }

TODO: study inconsistencies with QDataset Ops modp.

### Parameters

amount - a Datum
delta - a Datum

### Returns:

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

## numericalResolutionLimit

numericalResolutionLimit( Datum datum ) → Datum

return the numeric resolution of the Datum. Note some Datum implementations have additional information which allows the measurement resolution to be reflected as well, and this should be much smaller.

### Parameters

datum - a datum

### Returns:

a datum in the offset units.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( String s ) → Datum

attempt to parse the string as a datum. Note that if the units aren't specified, then of course the Datum will be assumed to be dimensionless. This also requires the the unit be registered already, and lookup should be used if the unit should be registered automatically. Strings containing the unit UTC are parsed as times. Strings containing an ISO8601 string like $Y-$m-$dT$H:$M are parsed as strings.

### Parameters

s - the string representing the Datum, e.g. "5 Hz" (but not 5Hz).

### Returns:

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

## parseValid

parseValid( String s ) → Datum

parse the string which contains a valid representation of a a Datum. A runtime exception is thrown when the string cannot be parsed.

### Parameters

s - the string representing the Datum, e.g. "5 Hz"

### Returns:

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

## splitDatumString

splitDatumString( String s ) → String[]

Split the string to separate magnitude component from units component. "5" → [ "5", "" ] "5 m" → [ "5", "m" ] "5m" → [ "5", "m" ] "4.5m^2" → [ "4.5", "m^2" ] "4.5e6m^2" → [ "4.5e6", "m^2" ] "-1" → [ "-1", "" ] "-1s" → [ "-1", "s" ] "-1.0e-6s" → [ "-1e-6", "s" ] "5 Deg N" → [ "5", "Deg N" ] " 10 days" → [ "10", "days" ] See http://jfaden.net:8080/hudson/job/autoplot-test037/ws/splitDatumString.jy

### Parameters

s - the string to break up

### Returns:

two element array
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## zeros

zeros( int count ) → String

return "0" for 0, "0.0" for 1, "0.00" for 2, and so on. This can be used in factory.newFormatter(formatString).

### Parameters

count - number of decimal places following the decimal.

### Returns:

string for newFormatter.

### See Also:

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