## org.das2.datum.DatumRangeUtil

Utility functions for DatumRanges.

## DatumRangeUtil( )

## iso8601duration

## iso8601DurationPattern

## createCentered

createCentered( Datum middle, Datum width ) → DatumRange

create a DatumRange with the value for the center, and the width.

### Parameters

middle - a Datum
width - a Datum

### Returns:

datumRange centered at middle with the given width.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## formatISO8601Datum

formatISO8601Datum( int[] result ) → String

for convenience, this formats the decomposed time.

### Parameters

result - seven-element time [ Y,m,d,H,M,S,nanos ]

### Returns:

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

## formatISO8601Duration

formatISO8601Duration( int[] t ) → String

format ISO8601 duration string, for example [1,0,0,1,0,0,0] → P1YT1H

### Parameters

t - 6 or 7-element array with [year,mon,day,hour,min,sec,nanos]

### Returns:

the formatted ISO8601 duration
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## formatTimeRange

formatTimeRange( DatumRange self ) → String

### Parameters

self - a DatumRange

### Returns:

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

## formatTimeRange

formatTimeRange( DatumRange self, boolean bothDoyYMD ) → String

format the time into an efficient string. This should be parseable.

### Parameters

self - a DatumRange
bothDoyYMD - if true, use $Y-$m-$d ($j) for formatting days.

### Returns:

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

## fuzzyEqual

fuzzyEqual( DatumRange timeRange1, DatumRange timeRange2, double percent ) → boolean

return true if the time ranges are overlapping with bounds within

### Parameters

timeRange1 - a DatumRange
timeRange2 - a DatumRange
percent - double from 0 to 100.

### Returns:

true if the two ranges are sufficiently close.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## generateList

generateList( DatumRange bounds, DatumRange element ) → java.util.List

return a list of DatumRanges that together cover the space identified by bounds. The list should contain one DatumRange that is equal to element, which should define the phase and period of the list elements. For example,

     DatumRange bounds= DatumRangeUtil.parseTimeRangeValid( '2006' );
     DatumRange first= DatumRangeUtil.parseTimeRangeValid( 'Jan 2006' );
     List list= generateList( bounds, first );

Note the procedure calls element.previous until bound.min() is contained, then calls bound.max until bound.max() is contained.

### Parameters

bounds - range to be covered.
element - range defining the width and phase of each list DatumRange.

### Returns:

the ranges covering the range.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## intersection

intersection( java.util.List bounds, java.util.List elements, boolean remove ) → java.util.List

return the elements of src that intersect with elements of the list contains. Both src and dst should be sorted lists that do not contain overlaps.

### Parameters

bounds - sorted list of non-overlapping ranges.
elements - sorted list of non-overlapping ranges. If remove is true, then the elements intersecting are removed and the result will contain non-overlapping elements.
remove - if true, remove intersecting elements from the elements list, leaving the elements that did not intersect with any of the ranges in bounds.

### Returns:

list of elements of src that overlap with elements of contains.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isAcceptable

isAcceptable( DatumRange dr, boolean log ) → boolean

put limits on the typical use when looking at data: * both min and max are finite numbers * time range is between year 1000 and year 3000. * log ranges span no more than 1e100 cycles.

### Parameters

dr - the DatumRange, which can contain infinite values that would make is inacceptable.
log - if true, then only allow 1e100 cycles.

### Returns:

true if the range is valid.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isISO8601Range

isISO8601Range( String stringIn ) → boolean

true true for parseable ISO8601 time ranges.

### Parameters

stringIn - a String

### Returns:

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

## main

main( String[] ss ) → void

### Parameters

ss - a java.lang.String[]

### Returns:

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

## newDimensionless

newDimensionless( double lower, double upper ) → DatumRange

create a new DatumRange. In the case where lower is greater than upper, the two will be reversed automatically.

### Parameters

lower - a double
upper - a double

### Returns:

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

## normalize

normalize( DatumRange dr, Datum d ) → double

returns the position within dr, where 0. is the dr.min(), and 1. is dr.max()

### Parameters

dr - a datum range with non-zero width.
d - a datum to normalize with respect to the range.

### Returns:

a double indicating the normalized datum.

### See Also:

rescale(org.das2.datum.DatumRange, double, double)
[search for examples] [view on GitHub] [view on old javadoc] [view source]
normalize( DatumRange dr, Datum d, boolean log ) → double [view source]

## normalizeLog

normalizeLog( DatumRange dr, Datum d ) → double

returns the position within dr, where 0. is the dr.min(), and 1. is dr.max()

### Parameters

dr - a datum range with non-zero width.
d - a datum to normalize with respect to the range.

### Returns:

a double indicating the normalized datum.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## normalizeTimeComponents

normalizeTimeComponents( int[] components ) → int[]

Normalize all the components, so no component is greater than its expected range or less than zero. Note that leap seconds are not accounted for. TODO: account for them.

### Parameters

components - int[7]: [ Y, m, d, H, M, S, nano ]

### Returns:

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

## parseDatumRange

parseDatumRange( String str, Units units ) → DatumRange

Parse the datum range in the context of units.

### Parameters

str - input like "5 to 15 cm"
units - unit like Units.km

### Returns:

the DatumRange
[search for examples] [view on GitHub] [view on old javadoc] [view source]
parseDatumRange( String str, DatumRange orig ) → DatumRange [view source]

## parseDatumRange

parseDatumRange( String str ) → DatumRange

This provides unambiguous rules for parsing all types datum ranges strictly from strings, with no out of band information. This was introduced to support das2stream parsing. Examples include: "2013 to 2015 UTC" "3 to 4 kg" "2015-05-05T00:00/2015-06-02T00:00"

### Parameters

str - the string representing a time.

### Returns:

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

## parseISO8601

parseISO8601( String str ) → int[]

Parser for ISO8601 formatted times. returns null or int[7]: [ Y, m, d, H, M, S, nano ] The code cannot parse any iso8601 string, but this code should. Right now it parses: "2012-03-27T12:22:36.786Z" "2012-03-27T12:22:36" (and some others) TODO: enumerate and test.

### Parameters

str - iso8601 string.

### Returns:

null or int[7]: [ Y, m, d, H, M, S, nano ]
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseISO8601Datum

parseISO8601Datum( String str, int[] result, int lsd ) → int

new attempt to write a clean ISO8601 parser. This should also parse 02:00 in the context of 2010-002T00:00/02:00. This does not support 2-digit years, which were removed in ISO 8601:2004. Sub-seconds (.123456789000) are truncated to nanosecond resolution.

### Parameters

str - the ISO8601 string
result - the datum, decomposed into [year,month,day,hour,minute,second,nano]
lsd - -1 or the current position ???

### Returns:

the lsd least significant digit
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseISO8601Duration

parseISO8601Duration( String stringIn ) → int[]

returns a 7 element array with [year,mon,day,hour,min,sec,nanos].

### Parameters

stringIn - a String

### Returns:

7-element array with [year,mon,day,hour,min,sec,nanos]
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseISO8601Range

parseISO8601Range( String stringIn ) → DatumRange

returns the time found in an iso8601 string, or null. This supports periods (durations) as in: 2007-03-01T13:00:00Z/P1Y2M10DT2H30M Other examples:

- 2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
- 2007-03-01T13:00:00Z/P1Y2M10DT2H30M
- P1Y2M10DT2H30M/2008-05-11T15:30:00Z
- 2007-03-01T00:00Z/P1D
- 2012-100T02:00/03:45
- 2001-01-01T06:08-0600/P1D Time zones (-0600) are supported though discouraged.

http://en.wikipedia.org/wiki/ISO_8601#Time_intervals

### Parameters

stringIn - a String

### Returns:

null or a DatumRange
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseRescaleStr

parseRescaleStr( String s, Datum[] result ) → Datum[]

parse position strings like "100%-5hr" into [ npos, datum ]. Note px is acceptable, but pt is proper. Ems are rounded to the nearest hundredth. Percents are returned as normal (0-1) and rounded to the nearest thousandth.

### Parameters

s - the string, like "100%-5hr"
result - a two-element Datum array with [npos,datum] result[1] provides the units.

### Returns:

a two-element Datum array with [npos,datum]
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parseTimeRange

parseTimeRange( String string ) → DatumRange

parse the string into a DatumRange with time location units. This parse allows several different forms of time ranges, such as:

- orbit:rbspa-pp:3 S/C orbits
- orbit:rbspa-pp:3-6 S/C orbits, three orbits.
- P10D the last 10 days, immediately resolved into static time range.
- 1972/now-P10D, immediately resolved into static time range.
- 1972/2002 ISO8601 time ranges
- 1972 to 2002 legacy das2 colloquial time ranges.
- lasthour/lasthour+P1H the hour we are within.

### Parameters

string - a String

### Returns:

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

## parseTimeRangeValid

parseTimeRangeValid( String s ) → DatumRange

parse the string into a DatumRange with time location units.

### Parameters

s - a String

### Returns:

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

## parseValidISO8601Range

parseValidISO8601Range( String stringIn ) → DatumRange

returns the time found in an iso8601 string, or throws a runtime exception.

### Parameters

stringIn - a String

### Returns:

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

## rescale

rescale( DatumRange dr, String rescale ) → DatumRange

rescale the DatumRange with a specification like "50%,150%" or "0%-1hr,100%+1hr". The string is spit on the comma the each is split on the % sign. This was originally introduced to support CreatePngWalk in Autoplot.

### Parameters

dr - a DatumRange
rescale - a String

### Returns:

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

## rescale

rescale( DatumRange dr, double min, double max ) → DatumRange

returns DatumRange relative to dr, where 0 is the minimum, and 1 is the maximum. For example rescale(1,2) is scanNext, rescale(-0.5,1.5) is zoomOut.

### Parameters

dr - a DatumRange with nonzero width.
min - the new min normalized with respect to this range. 0. is this range's min, 1 is this range's max
max - the new max with normalized wrt this range. 0. is this range's min, 1 is this range's max.

### Returns:

new DatumRange.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## rescale

rescale( DatumRange dr, double n ) → Datum

returns Datum relative to dr, where 0 is the minimum, and 1 is the maximum.

### Parameters

dr - a DatumRange with nonzero width.
n - the location normalized with respect to this range. 0. is the range's min, 1 is the range's max.

### Returns:

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

## rescaleInverse

rescaleInverse( DatumRange dr, String rescale ) → DatumRange

rescale the DatumRange with a specification like "50%,150%" or "0%-1hr,100%+1hr". The string is split on the comma the each is split on the % sign. This was originally introduced to support CreatePngWalk in Autoplot.

### Parameters

dr - a DatumRange
rescale - a String

### Returns:

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

## rescaleInverse

rescaleInverse( DatumRange dr, double min, double max ) → DatumRange

inverse of rescale function

### Parameters

dr - a DatumRange with nonzero width.
min - the new min normalized with respect to this range. 0. is this range's min, 1 is this range's max
max - the new max with normalized wrt this range. 0. is this range's min, 1 is this range's max.

### Returns:

new DatumRange.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## rescaleLog

rescaleLog( DatumRange dr, double min, double max ) → DatumRange

returns DatumRange relative to this, where 0. is the minimum, and 1. is the maximum, but the scaling is done in the log space. For example, rescaleLog( [0.1,1.0], -1, 2 ) → [ 0.01, 10.0 ]

### Parameters

dr - a DatumRange with nonzero width.
min - the new min normalized with respect to this range. 0. is this range's min, 1 is this range's max, 0 is min-width.
max - the new max with normalized wrt this range. 0. is this range's min, 1 is this range's max, 0 is min-width.

### Returns:

new DatumRange.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## roundSections

roundSections( DatumRange dr, int n ) → DatumRange

round to a nice interval with very roughly n divisions. For example,

       -0.048094730687625806 to 0.047568, 100  → -0.048 to 0.048
       2012-04-18 0:00:00 to 23:59:40, 24 → 2012-04-18
       2014-08-10 0:00:00 to 2014-08-11T00:00:59, 24 → 2014-08-10

### Parameters

dr - a DatumRange
n - an int

### Returns:

dr when its width is zero, or a rounded range.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setUseDoy

setUseDoy( boolean v ) → void

### Parameters

v - a boolean

### Returns:

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

## sloppyContains

sloppyContains( DatumRange context, Datum datum ) → boolean

Like DatumRange.contains, but includes the end point. Often this allows for simpler code.

### Parameters

context - the datum range.
datum - the data point

### Returns:

true if the range contains the datum.

### See Also:

DatumRange#contains(org.das2.datum.DatumRange)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## sloppyIntersection

sloppyIntersection( DatumRange range, DatumRange include ) → DatumRange

Like DatumRange.intersects, but returns a zero-width range when the two do not intersect. When they do not intersect, the min or max of the first range is returned, depending on whether or not the second range is above or below the first range. Often this allows for simpler code.

### Parameters

range - the first DatumRange
include - the second DatumRange

### Returns:

a DatumRange that contains parts of both ranges, or is zero-width.

### See Also:

DatumRange#intersection(org.das2.datum.DatumRange)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toStringInclusive

toStringInclusive( DatumRange datumRange ) → String

represent the string to indicate that the calling code will also consider the maximum value part of the datum range. This once added the text "(including...)," but this isn't terribly necessary and creates clutter on some plots.

### Parameters

datumRange - "5 to 15 Kg"

### Returns:

"5 to 15 Kg"
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## union

union( Datum d1, Datum d2 ) → DatumRange

return a datum range that sloppily covers the d1 and d2. (The bigger of the two will be the exclusive max.)

### Parameters

d1 - a Datum
d2 - a Datum

### Returns:

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

## union

union( DatumRange range, Datum include ) → DatumRange

return the union of a DatumRange and Datum. If they do not intersect, the range between the two is included as well.

### Parameters

range - the range or null. If range is null, then new DatumRange( include, include ) is returned.
include - a datum to add this this range. If its the max, then it will be the end of the datum range, not included.

### Returns:

DatumRange containing all three boundaries of the range and datum
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## union

union( DatumRange range, DatumRange include ) → DatumRange

return the union of two DatumRanges. If they do not intersect, the range between the two is included as well.

### Parameters

range - the range, or null. If range is null then include is returned.
include - the DatumRange to include.

### Returns:

DatumRange containing all four boundaries of the two datum ranges.
[search for examples] [view on GitHub] [view on old javadoc] [view source]