DatumRange

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

Direct Known Subclasses:

MonthDatumRange, OrbitDatumRange
```
public class DatumRange
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable
```
A DatumRange is provided as a means to carry an ordered pair of Datums representing an interval. This sort of data structure comes up often in processing, and it's useful to define once and get the operators implemented correctly. Consider using this object whenever you see pairs of Datums in interfaces and codes (e.g. tbegin,tend), they are probably a DatumRange!

See Also:

mutable object used to link two axes together., Serialized Form

Constructor Summary

Constructors
Constructor and Description
`DatumRange(Datum s1, Datum s2)` Creates valid DatumRange from two Datums.
`DatumRange(double s1, double s2, Units units)` create a datum range from two doubles in the context of units.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`int`	`compareTo(java.lang.Object o)` Compare this to another DatumRange, ordered by the lesser datum, then the greater datum.
`boolean`	`contains(Datum d)` returns true if the Datum is in the range, inclusive of the lesser point but exclusive of the greater point.
`boolean`	`contains(DatumRange dr)` returns true of param dr is contained by this, so that this.union(dr).equals(this).
`DatumRange`	`convertTo(Units u)` return this DatumRange in new units.
`boolean`	`equals(java.lang.Object o)` returns true if the two endpoints are equal.
`Units`	`getUnits()` return the units of the DatumRange.
`int`	`hashCode()`
`DatumRange`	`include(Datum d)` return a new DatumRange that includes the given Datum, extending the range if necessary.
`DatumRange`	`intersection(DatumRange dr)` returns the intersection of the two intersecting ranges.
`boolean`	`intersects(DatumRange dr)` returns true of the DatumRange overlaps this.
`Datum`	`max()` returns the bigger value or stop of the range.
`Datum`	`middle()` returns the middle value of the range, often useful when the most descriptive value is needed.
`Datum`	`min()` returns the smaller value or start of the range.
`static DatumRange`	`newDatumRange(double min, double max, Units units)` Deprecated.
`static DatumRange`	`newRange(Datum lower, Datum upper)` create a new DatumRange.
`static DatumRange`	`newRange(double lower, double upper)` create a new DatumRange.
`static DatumRange`	`newRange(double lower, double upper, Units units)` create a new DatumRange.
`DatumRange`	`next()` returns the next DatumRange covering the space defined by Units.
`DatumRange`	`previous()` returns the previous DatumRange covering the space defined by Units.
`DatumRange`	`rescale(double min, double max)` returns DatumRange relative to this, where 0.0 is the minimum, and 1.0 is the maximum.
`java.lang.String`	`toString()` returns a human consumable representation of the string.
`DatumRange`	`union(DatumRange dr)` returns the union of the two intersecting or adjacent ranges.
`Datum`	`width()` returns the width of the range, which is simply the greater minus the lessor.
`DatumRange`	`zoomOut(double factor)` returns a scaled DatumRange, with a new width that is the this datumRange's width multiplied by factor, and the same center.

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

- Constructor Detail
  - DatumRange
```
public DatumRange(Datum s1,
                  Datum s2)
```
    Creates valid DatumRange from two Datums.
    
    Parameters:
    
    s1 - the start or smaller value of the range.
    
    s2 - the stop or bigger value of the range.
  - DatumRange
```
public DatumRange(double s1,
                  double s2,
                  Units units)
```
    create a datum range from two doubles in the context of units.
    
    Parameters:
    
    s1 - the start or smaller value of the range.
    
    s2 - the stop or bigger value of the range.
    
    units - the units in which to interpret s1 and s2.
- Method Detail
  - intersects
```
public boolean intersects(DatumRange dr)
```
    returns true of the DatumRange overlaps this. Note that the endpoints are not included in the comparison, so that Tuesday.intersects(Wednesday)==false.
    
    Parameters:
    
    dr - a valid datum range
    
    Returns:
    
    true of the DatumRange overlaps this
    
    Throws:
    
    InconvertibleUnitsException - if the units can not be reconciled.
  - intersection
```
public DatumRange intersection(DatumRange dr)
```
    returns the intersection of the two intersecting ranges. This is a range that contains(d) if and only if this.contains(d) and dr.contains(d).
    
    Parameters:
    
    dr - a valid datum range.
    
    Returns:
    
    the intersection of the two intersecting ranges.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the two do not overlap.
    
    See Also:
    
    DatumRangeUtil.sloppyIntersection(org.das2.datum.DatumRange, org.das2.datum.DatumRange)
  - contains
```
public boolean contains(DatumRange dr)
```
    returns true of param dr is contained by this, so that this.union(dr).equals(this).
    
    Parameters:
    
    dr - the datum range to test.
    
    Returns:
    
    true iff this.union(dr).equals(this);
  - union
```
public DatumRange union(DatumRange dr)
```
    returns the union of the two intersecting or adjacent ranges.
    
    Parameters:
    
    dr - the other range of consistent units.
    
    Returns:
    
    DatumRange union of the two DatumRanges
    
    Throws:
    
    java.lang.IllegalArgumentException - if the two are disjoint.
  - contains
```
public boolean contains(Datum d)
```
    returns true if the Datum is in the range, inclusive of the lesser point but exclusive of the greater point.
    
    Parameters:
    
    d - the datum
    
    Returns:
    
    true if d is in the range, exclusive of max.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the units cannot be converted.
  - width
```
public Datum width()
```
    returns the width of the range, which is simply the greater minus the lessor. Note that the units of the result will not necessarily be the same as the endpoints, for example with LocationDatums.
    
    Returns:
    
    Datum that is the width of the range (max.subtract(min)).
  - toString
```
public java.lang.String toString()
```
    returns a human consumable representation of the string. This should also be parsable with DatumRangeUtil.parseDatumRange, but this has not been verified to complete certainty.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the DatumRange as a String.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object o)
```
    returns true if the two endpoints are equal.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    o -
    
    Returns:
  - compareTo
```
public int compareTo(java.lang.Object o)
```
    Compare this to another DatumRange, ordered by the lesser datum, then the greater datum. This is mostly provided for .equals, but also so there is a consistent ordering convention though out the system.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable
    
    Parameters:
    
    o - the DatumRange to compare this DatumRange to.
    
    Returns:
    
    an int < 0 if this comes before DatumRange a in this DatumRange's units space, 0 if they are equal, and > 0 otherwise.
  - zoomOut
```
public DatumRange zoomOut(double factor)
```
    returns a scaled DatumRange, with a new width that is the this datumRange's width multiplied by factor, and the same center. 1.0 is the same range, 2.0 has twice the width, etc.
    
    Parameters:
    
    factor - double representing the new range's width divided by this range's width.
    
    Returns:
    
    a scaled DatumRange, with a new width that is the this datumRange's width multiplied by factor, and the same center.
  - rescale
```
public DatumRange rescale(double min,
                          double max)
```
    returns DatumRange relative to this, where 0.0 is the minimum, and 1.0 is the maximum. For example rescale(1,2) is scanNext, rescale(-0.5,1.5) is zoomOut.
    
    Parameters:
    
    min - the new min normalized with respect to this range. 0.0 is this range's min, 1.0 is this range's max.
    
    max - the new max with normalized with respect to this range. 0.0 is this range's min, 1.0 is this range's max.
    
    Returns:
    
    new DatumRange.
    
    See Also:
    
    DatumRangeUtil.rescale(org.das2.datum.DatumRange, double, double)
  - min
```
public Datum min()
```
    returns the smaller value or start of the range.
    
    Returns:
    
    the smaller value or start of the range.
  - max
```
public Datum max()
```
    returns the bigger value or stop of the range.
    
    Returns:
    
    the bigger value or stop of the range.
  - middle
```
public Datum middle()
```
    returns the middle value of the range, often useful when the most descriptive value is needed.
    
    Returns:
    
    the middle value of the range.
  - next
```
public DatumRange next()
```
    returns the next DatumRange covering the space defined by Units. Typically, this will be a range with a min equal to this datum's max, and the same width. Some implementations of DatumRange may return a range with a different width than this DatumRange's width, for example, when advancing month-by-month with a MonthDatumRange. When there is no next interval, then this same range will be returned.
    
    Returns:
    
    the next DatumRange covering the space defined by Units.
  - previous
```
public DatumRange previous()
```
    returns the previous DatumRange covering the space defined by Units. See next(). When there is no previous interval, then this same range will be returned.
    
    Returns:
    
    the previous DatumRange covering the space defined by Units
  - convertTo
```
public DatumRange convertTo(Units u)
```
    return this DatumRange in new units. Note this may cause some functions of a DatumRange to change, such as the next() for a MonthDatumRange, but implementations should attempt to preserve type.
    
    Parameters:
    
    u - the new units.
    
    Returns:
    
    the DatumRange in the new units.
  - include
```
public DatumRange include(Datum d)
```
    return a new DatumRange that includes the given Datum, extending the range if necessary. For example,
```
 [0,1).include(2)→ [0,2)  (note this is exclusive of 2 since it's the end).
 [0,1).include(-1)→ [-1,1).
 [0,1).include(0.5) → [0,1]  (and returns the same DatumRange object)
 
```
    Also, including a fill Datum returns the same DatumRange as well.
    Parameters:
    
    d - the Datum to include
    
    Returns:
    
    the new range.
  - getUnits
```
public Units getUnits()
```
    return the units of the DatumRange.
    
    Returns:
    
    the units of the DatumRange.
  - newDatumRange
```
public static DatumRange newDatumRange(double min,
                                       double max,
                                       Units units)
```
    Deprecated.
    
    creates a new DatumRange object with the range specified in the space identified by units. Note that min must be <= max.
    
    Parameters:
    
    min - the minimum value
    
    max - the maximum value which is greater than or equal to the min.
    
    units - the units of the two doubles.
    
    Returns:
    
    the DatumRange
    
    See Also:
    
    newRange(double, double)
  - newRange
```
public static DatumRange newRange(Datum lower,
                                  Datum upper)
```
    create a new DatumRange. In the case where lower is greater than upper, the two will be reversed automatically.
    
    Parameters:
    
    lower - the lower bound
    
    upper - the upper bound
    
    Returns:
    
    a new DatumRange
  - newRange
```
public static DatumRange newRange(double lower,
                                  double upper,
                                  Units units)
```
    create a new DatumRange. In the case where lower is greater than upper, the two will be reversed automatically.
    
    Parameters:
    
    lower - the lower bound
    
    upper - the upper bound
    
    units - the units
    
    Returns:
    
    a new DatumRange
  - newRange
```
public static DatumRange newRange(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:

Class DatumRange

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DatumRange

DatumRange

Method Detail

intersects

intersection

contains

union

contains

width

toString

hashCode

equals

compareTo

zoomOut

rescale

min

max

middle

next

previous

convertTo

include

getUnits

newDatumRange

newRange

newRange

newRange