org.das2.datum
Class DatumRange

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

All Implemented Interfaces:

java.lang.Comparable

Direct Known Subclasses:

MonthDatumRange

public class DatumRange
extends java.lang.Object
implements java.lang.Comparable

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!

Constructor Summary

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

int	compareTo(java.lang.Object o) Ordered by the lesser point, then the greater point.
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).
boolean	equals(java.lang.Object o) returns true if the two endpoints are equal.
Units	getUnits() return the units of the DatumRange.
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	min() returns the smaller value or start of the range.
static DatumRange	newDatumRange(double min, double max, Units units) creates a new DatumRange object with the range specified in the space identified by units.
DatumRange	next() returns the next DatumRange covering the space defined by Units.
double	normalize(Datum d) returns the position within this, where 0.
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.
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, hashCode, 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:

InconvertableUnitsException - 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

contains

public boolean contains(DatumRange dr)

returns true of @param dr is contained by this, so that this.union(dr).equals(this).

Parameters:

dr -

union

public DatumRange union(DatumRange dr)

returns the union of the two intersecting or adjacent ranges.

Parameters:

dr -

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 -

Returns:

true if d is in the range, exclusive of max.

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.

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)

Ordered by the lesser point, then the greater point. This is mostly provided for .equals, but also so there is a consistent ordering convention thoughout the system.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o -

Returns:

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. is the minimum, and 1. 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. 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.

normalize

public double normalize(Datum d)

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

Parameters:

d - a datum to normalize with respect to the range.

Returns:

a double indicating the normalized datum.

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.

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.

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().

Returns:

the previous DatumRange covering the space defined by 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.

getUnits

public Units getUnits()

return the units of the DatumRange.

newDatumRange

public static DatumRange newDatumRange(double min,
                                       double max,
                                       Units units)

creates a new DatumRange object with the range specified in the space identified by units. Note that min must be <= max.