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( DatumRange self, boolean bothDoyYMD ) → String

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

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
parseDatumRange( String str ) → DatumRange

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. TODO: this should use parseISO8601Datum.

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.

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:

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:

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( DatumRange dr, double min, double max ) → DatumRange
rescale( DatumRange dr, double n ) → Datum

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( DatumRange dr, double min, double max ) → DatumRange

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( DatumRange range, Datum include ) → DatumRange
union( DatumRange range, DatumRange include ) → DatumRange