DatumRangeUtil

java.lang.Object
- org.das2.datum.DatumRangeUtil

public class DatumRangeUtil
extends java.lang.Object

Utility functions for DatumRanges.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class DatumRangeUtil.DateDescriptor

Nested Classes
Modifier and Type	Class and Description
`static class`	`DatumRangeUtil.DateDescriptor`

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String iso8601duration

static java.util.regex.Pattern iso8601DurationPattern

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`iso8601duration`
`static java.util.regex.Pattern`	`iso8601DurationPattern`

Constructor Summary

Constructors
Constructor and Description

DatumRangeUtil()

Constructors
Constructor and Description
`DatumRangeUtil()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static DatumRange`	`createCentered(Datum middle, Datum width)` create a DatumRange with the value for the center, and the width.
`static java.lang.String`	`formatISO8601Datum(int[] result)` for convenience, this formats the decomposed time.
`static java.lang.String`	`formatISO8601Duration(int[] t)` format ISO8601 duration string, for example [1,0,0,1,0,0,0] → P1YT1H
`static java.lang.String`	`formatTimeRange(DatumRange self)`
`static java.lang.String`	`formatTimeRange(DatumRange self, boolean bothDoyYMD)` format the time into an efficient string.
`static boolean`	`fuzzyEqual(DatumRange timeRange1, DatumRange timeRange2, double percent)` return true if the time ranges are overlapping with bounds within
`static java.util.List<DatumRange>`	`generateList(DatumRange bounds, DatumRange element)` return a list of DatumRanges that together cover the space identified by bounds.
`static java.util.List<DatumRange>`	`intersection(java.util.List<DatumRange> bounds, java.util.List<DatumRange> elements, boolean remove)` return the elements of src that intersect with elements of the list contains.
`static boolean`	`isAcceptable(DatumRange dr, boolean log)` 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.
`static boolean`	`isISO8601Range(java.lang.String stringIn)` true true for parseable ISO8601 time ranges.
`static void`	`main(java.lang.String[] ss)`
`static DatumRange`	`newDimensionless(double lower, double upper)` create a new DatumRange.
`static double`	`normalize(DatumRange dr, Datum d)` returns the position within dr, where 0.
`static double`	`normalize(DatumRange dr, Datum d, boolean log)`
`static double`	`normalizeLog(DatumRange dr, Datum d)` returns the position within dr, where 0.
`static int[]`	`normalizeTimeComponents(int[] components)` Normalize all the components, so no component is greater than its expected range or less than zero.
`static DatumRange`	`parseDatumRange(java.lang.String str)` This provides unambiguous rules for parsing all types datum ranges strictly from strings, with no out of band information.
`static DatumRange`	`parseDatumRange(java.lang.String str, DatumRange orig)`
`static DatumRange`	`parseDatumRange(java.lang.String str, Units units)` Parse the datum range in the context of units.
`static int[]`	`parseISO8601(java.lang.String str)` Parser for ISO8601 formatted times.
`static int`	`parseISO8601Datum(java.lang.String str, int[] result, int lsd)` new attempt to write a clean ISO8601 parser.
`static int[]`	`parseISO8601Duration(java.lang.String stringIn)` returns a 7 element array with [year,mon,day,hour,min,sec,nanos].
`static DatumRange`	`parseISO8601Range(java.lang.String stringIn)` returns the time found in an iso8601 string, or null.
`static Datum[]`	`parseRescaleStr(java.lang.String s, Datum[] result)` parse position strings like "100%-5hr" into [ npos, datum ].
`static DatumRange`	`parseTimeRange(java.lang.String string)` parse the string into a DatumRange with time location units.
`static DatumRange`	`parseTimeRangeValid(java.lang.String s)` parse the string into a DatumRange with time location units.
`static DatumRange`	`parseValidISO8601Range(java.lang.String stringIn)` returns the time found in an iso8601 string, or throws a runtime exception.
`static Datum`	`rescale(DatumRange dr, double n)` returns Datum relative to dr, where 0 is the minimum, and 1 is the maximum.
`static DatumRange`	`rescale(DatumRange dr, double min, double max)` returns DatumRange relative to dr, where 0 is the minimum, and 1 is the maximum.
`static DatumRange`	`rescale(DatumRange dr, java.lang.String rescale)` rescale the DatumRange with a specification like "50%,150%" or "0%-1hr,100%+1hr".
`static DatumRange`	`rescaleInverse(DatumRange dr, double min, double max)` inverse of rescale function
`static DatumRange`	`rescaleInverse(DatumRange dr, java.lang.String rescale)` rescale the DatumRange with a specification like "50%,150%" or "0%-1hr,100%+1hr".
`static DatumRange`	`rescaleLog(DatumRange dr, double min, double max)` returns DatumRange relative to this, where 0.
`static DatumRange`	`roundSections(DatumRange dr, int n)` round to a nice interval with very roughly n divisions.
`static void`	`setUseDoy(boolean v)`
`static boolean`	`sloppyContains(DatumRange context, Datum datum)` Like DatumRange.contains, but includes the end point.
`static DatumRange`	`sloppyIntersection(DatumRange range, DatumRange include)` Like DatumRange.intersects, but returns a zero-width range when the two do not intersect.
`static java.lang.String`	`toStringInclusive(DatumRange datumRange)` represent the string to indicate that the calling code will also consider the maximum value part of the datum range.
`static DatumRange`	`union(Datum d1, Datum d2)` return a datum range that sloppily covers the d1 and d2.
`static DatumRange`	`union(DatumRange range, Datum include)` return the union of a DatumRange and Datum.
`static DatumRange`	`union(DatumRange range, DatumRange include)` return the union of two DatumRanges.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - iso8601duration
```
public static final java.lang.String iso8601duration
```
    See Also:
    
    Constant Field Values
  - iso8601DurationPattern
```
public static final java.util.regex.Pattern iso8601DurationPattern
```
- Constructor Detail
  - DatumRangeUtil
```
public DatumRangeUtil()
```
- Method Detail
  - isAcceptable
```
public static boolean isAcceptable(DatumRange dr,
                                   boolean log)
```
    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.
  - toStringInclusive
```
public static java.lang.String toStringInclusive(DatumRange datumRange)
```
    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"
  - formatISO8601Datum
```
public static java.lang.String formatISO8601Datum(int[] result)
```
    for convenience, this formats the decomposed time.
    
    Parameters:
    
    result - seven-element time [ Y,m,d,H,M,S,nanos ]
    
    Returns:
    
    formatted time
  - parseISO8601Datum
```
public static int parseISO8601Datum(java.lang.String str,
                                    int[] result,
                                    int lsd)
```
    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
  - normalizeTimeComponents
```
public static int[] normalizeTimeComponents(int[] components)
```
    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
  - parseISO8601
```
public static int[] parseISO8601(java.lang.String str)
```
    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 ]
  - parseISO8601Duration
```
public static int[] parseISO8601Duration(java.lang.String stringIn)
                                  throws java.text.ParseException
```
    returns a 7 element array with [year,mon,day,hour,min,sec,nanos].
    
    Parameters:
    
    stringIn -
    
    Returns:
    
    7-element array with [year,mon,day,hour,min,sec,nanos]
    
    Throws:
    
    java.text.ParseException - if the string does not appear to be valid.
  - formatISO8601Duration
```
public static java.lang.String formatISO8601Duration(int[] t)
```
    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
  - isISO8601Range
```
public static boolean isISO8601Range(java.lang.String stringIn)
```
    true true for parseable ISO8601 time ranges.
    
    Parameters:
    
    stringIn -
    
    Returns:
  - parseISO8601Range
```
public static DatumRange parseISO8601Range(java.lang.String stringIn)
                                    throws java.text.ParseException
```
    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 -
    
    Returns:
    
    null or a DatumRange
    
    Throws:
    
    java.text.ParseException
  - parseValidISO8601Range
```
public static DatumRange parseValidISO8601Range(java.lang.String stringIn)
```
    returns the time found in an iso8601 string, or throws a runtime exception.
    
    Parameters:
    
    stringIn -
    
    Returns:
  - main
```
public static void main(java.lang.String[] ss)
                 throws java.text.ParseException
```
    Throws:
    
    java.text.ParseException
  - parseTimeRange
```
public static DatumRange parseTimeRange(java.lang.String string)
                                 throws java.text.ParseException
```
    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 -
    
    Returns:
    
    the range interpreted.
    
    Throws:
    
    java.text.ParseException - when the string cannot be parsed.
    
    java.lang.IllegalArgumentException - when an orbits file cannot be read
  - parseTimeRangeValid
```
public static DatumRange parseTimeRangeValid(java.lang.String s)
```
    parse the string into a DatumRange with time location units.
    
    Parameters:
    
    s -
    
    Returns:
    
    Throws:
    
    java.lang.IllegalArgumentException - when the string cannot be parsed.
  - setUseDoy
```
public static void setUseDoy(boolean v)
```
  - formatTimeRange
```
public static java.lang.String formatTimeRange(DatumRange self)
```
  - formatTimeRange
```
public static java.lang.String formatTimeRange(DatumRange self,
                                               boolean bothDoyYMD)
```
    format the time into an efficient string. This should be parseable.
    
    Parameters:
    
    self -
    
    bothDoyYMD - if true, use $Y-$m-$d ($j) for formatting days.
    
    Returns:
  - generateList
```
public static java.util.List<DatumRange> generateList(DatumRange bounds,
                                                      DatumRange element)
```
    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.
  - newDimensionless
```
public static DatumRange newDimensionless(double lower,
                                          double upper)
```
    create a new DatumRange. In the case where lower is greater than upper, the two will be reversed automatically.
    
    Parameters:
    
    lower -
    
    upper -
    
    Returns:
  - parseDatumRange
```
public static DatumRange parseDatumRange(java.lang.String str,
                                         Units units)
                                  throws java.text.ParseException
```
    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
    
    Throws:
    
    java.text.ParseException
  - parseDatumRange
```
public static DatumRange parseDatumRange(java.lang.String str,
                                         DatumRange orig)
                                  throws java.text.ParseException
```
    Throws:
    
    java.text.ParseException
  - parseDatumRange
```
public static DatumRange parseDatumRange(java.lang.String str)
                                  throws java.text.ParseException
```
    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.
    
    Throws:
    
    java.text.ParseException
  - parseRescaleStr
```
public static Datum[] parseRescaleStr(java.lang.String s,
                                      Datum[] result)
                               throws java.text.ParseException
```
    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]
    
    Throws:
    
    java.text.ParseException
  - rescale
```
public static DatumRange rescale(DatumRange dr,
                                 java.lang.String rescale)
                          throws java.text.ParseException
```
    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 -
    
    rescale -
    
    Returns:
    
    Throws:
    
    java.text.ParseException
  - rescaleInverse
```
public static DatumRange rescaleInverse(DatumRange dr,
                                        java.lang.String rescale)
                                 throws java.text.ParseException
```
    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 -
    
    rescale -
    
    Returns:
    
    Throws:
    
    java.text.ParseException
  - rescale
```
public static DatumRange rescale(DatumRange dr,
                                 double min,
                                 double max)
```
    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.
  - rescale
```
public static Datum rescale(DatumRange dr,
                            double n)
```
    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
  - rescaleInverse
```
public static DatumRange rescaleInverse(DatumRange dr,
                                        double min,
                                        double max)
```
    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.
  - rescaleLog
```
public static DatumRange rescaleLog(DatumRange dr,
                                    double min,
                                    double max)
```
    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.
  - createCentered
```
public static DatumRange createCentered(Datum middle,
                                        Datum width)
```
    create a DatumRange with the value for the center, and the width.
    
    Parameters:
    
    middle -
    
    width -
    
    Returns:
    
    datumRange centered at middle with the given width.
  - normalize
```
public static double normalize(DatumRange dr,
                               Datum d)
```
    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)
  - normalize
```
public static double normalize(DatumRange dr,
                               Datum d,
                               boolean log)
```
  - normalizeLog
```
public static double normalizeLog(DatumRange dr,
                                  Datum d)
```
    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.
  - sloppyIntersection
```
public static DatumRange sloppyIntersection(DatumRange range,
                                            DatumRange include)
```
    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)
  - intersection
```
public static java.util.List<DatumRange> intersection(java.util.List<DatumRange> bounds,
                                                      java.util.List<DatumRange> elements,
                                                      boolean remove)
```
    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.
  - sloppyContains
```
public static boolean sloppyContains(DatumRange context,
                                     Datum datum)
```
    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)
  - union
```
public static DatumRange union(Datum d1,
                               Datum d2)
```
    return a datum range that sloppily covers the d1 and d2. (The bigger of the two will be the exclusive max.)
    
    Parameters:
    
    d1 -
    
    d2 -
    
    Returns:
    
    Throws:
    
    InconvertibleUnitsException
  - union
```
public static DatumRange union(DatumRange range,
                               Datum include)
```
    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
    
    Throws:
    
    InconvertibleUnitsException
  - union
```
public static DatumRange union(DatumRange range,
                               DatumRange include)
```
    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.
    
    Throws:
    
    InconvertibleUnitsException
  - fuzzyEqual
```
public static boolean fuzzyEqual(DatumRange timeRange1,
                                 DatumRange timeRange2,
                                 double percent)
```
    return true if the time ranges are overlapping with bounds within
    
    Parameters:
    
    timeRange1 -
    
    timeRange2 -
    
    percent - double from 0 to 100.
    
    Returns:
    
    true if the two ranges are sufficiently close.
  - roundSections
```
public static DatumRange roundSections(DatumRange dr,
                                       int n)
```
    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 -
    
    n -
    
    Returns:
    
    dr when its width is zero, or a rounded range.

Class DatumRangeUtil

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

iso8601duration

iso8601DurationPattern

Constructor Detail

DatumRangeUtil

Method Detail

isAcceptable

toStringInclusive

formatISO8601Datum

parseISO8601Datum

normalizeTimeComponents

parseISO8601

parseISO8601Duration

formatISO8601Duration

isISO8601Range

parseISO8601Range

parseValidISO8601Range

main

parseTimeRange

parseTimeRangeValid

setUseDoy

formatTimeRange

formatTimeRange

generateList

newDimensionless

parseDatumRange

parseDatumRange

parseDatumRange

parseRescaleStr

rescale

rescaleInverse

rescale

rescale

rescaleInverse

rescaleLog

createCentered

normalize

normalize

normalizeLog

sloppyIntersection

intersection

sloppyContains

union

union

union

fuzzyEqual

roundSections