org.tridas.io.util
Class YearRange

java.lang.Object
  org.tridas.io.util.YearRange

All Implemented Interfaces:

Comparable

public class YearRange
extends Object
implements Comparable

A range of years. Ranges are immutable; all otherwise-destructive operations on a Range return a new Range.

Author:

Ken Harris

See Also:

SafeIntYear, TreeRingData

Constructor Summary

YearRange()
Construct a new empty range, starting at Year.DEFAULT.

YearRange(AstronomicalYear y1, AstronomicalYear y2)
Construct a new range using Astronomical years

YearRange(org.tridas.interfaces.ITridasSeries series)
Create a range from a Tridas series.

YearRange(SafeIntYear y, int span)
Construct a range, given a starting year and span.

YearRange(SafeIntYear y1, SafeIntYear y2)
Construct a new range, from y₁ to y₂.

YearRange(String s)
Construct a range from a String.

Method Summary

int	compareTo(Object o) Compares this and o, for placing in fallback order.
boolean	contains(SafeIntYear y) Return true if (and only if) the given year is inside the range, inclusive.
boolean	contains(YearRange r) Return true if (and only if) the given range is completely inside the range, inclusive.
boolean	endOfRow(SafeIntYear y) Return true, iff this year is the end of a row.
boolean	equals(Object o) Compare two ranges for equality.
SafeIntYear	getEnd() Get the ending year of this range.
SafeIntYear	getStart() Get the starting year of this range.
int	hashCode() A hash code for the Range.
YearRange	intersection(YearRange r) The intersection of this range with r.
int	overlap(YearRange r) Return the number of years overlap between this range and the given range.
YearRange	redateBy(int dy) Redate a range by a certain number of years.
YearRange	redateEndTo(SafeIntYear y) Set the ending year of the range, and adjust the start year to maintain the same length.
YearRange	redateStartTo(SafeIntYear y) Set the starting year of the range, and adjust the ending year to maintain the same length.
int	rows() Compute the number of rows this Range will take to display, assuming rows are marked off as the row() method does.
int	span() Return the number of years spanned by this range.
boolean	startOfRow(SafeIntYear y) Return true, iff this year is the start of a row.
String	toString() Return a simple string representation of the range, like "1001 - 1036".
String	toStringWithSpan() Return a string representation of the range, including the span, like "(1001 - 1036, n=36)".
YearRange	union(YearRange r) The union of this range with r.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

YearRange

public YearRange()

Construct a new empty range, starting at Year.DEFAULT.

See Also:

SafeIntYear

YearRange

public YearRange(SafeIntYear y1,
                 SafeIntYear y2)

Construct a new range, from y₁ to y₂. (Neither year may be null.) If y₂ < y₁, it is an empty interval.

Parameters:

y1 - starting year

y2 - ending year

YearRange

public YearRange(SafeIntYear y,
                 int span)

Construct a range, given a starting year and span.

Parameters:

y - the starting year

span - the number of years

YearRange

public YearRange(String s)

Construct a range from a String.

Parameters:

s - the String

YearRange

public YearRange(org.tridas.interfaces.ITridasSeries series)

Create a range from a Tridas series. This attempts to extract a range using the interpretation.firstyear and interpretation.lastyear values. If the firstyear is null then it sets this to 1001. If the last year is null, then it sets it to first year + count of data values.

Parameters:

series -

YearRange

public YearRange(AstronomicalYear y1,
                 AstronomicalYear y2)

Construct a new range using Astronomical years

Parameters:

y1 - starting year

y2 - ending year

Method Detail

getStart

public SafeIntYear getStart()

Get the starting year of this range.

Returns:

the starting year

getEnd

public SafeIntYear getEnd()

Get the ending year of this range.

Returns:

the ending year

redateStartTo

public YearRange redateStartTo(SafeIntYear y)

Set the starting year of the range, and adjust the ending year to maintain the same length.

Parameters:

y - new starting year for the range

See Also:

redateEndTo(org.tridas.io.util.SafeIntYear)

redateBy

public YearRange redateBy(int dy)

Redate a range by a certain number of years. Usually, you'll use redateStartTo() or redateEndTo(), which are more convenient.

Parameters:

dy - the number of years to shift this range by

redateEndTo

public YearRange redateEndTo(SafeIntYear y)

Set the ending year of the range, and adjust the start year to maintain the same length.

Parameters:

y - new ending year for the range

See Also:

redateStartTo(org.tridas.io.util.SafeIntYear)

span

public int span()

Return the number of years spanned by this range. For example, the range 1001 - 1005 spans 5 years.

Returns:

the span of this range (difference between start and end, inclusive)

rows

public int rows()

Compute the number of rows this Range will take to display, assuming rows are marked off as the row() method does.

Returns:

the number of rows this range spans

toString

public String toString()

Return a simple string representation of the range, like "1001 - 1036".

Overrides:

toString in class Object

Returns:

a string representation of the range

toStringWithSpan

public String toStringWithSpan()

Return a string representation of the range, including the span, like "(1001 - 1036, n=36)".

Returns:

a string representation of the range, including span

contains

public boolean contains(SafeIntYear y)

Return true if (and only if) the given year is inside the range, inclusive.

Parameters:

y - year to check

Returns:

true if y is in the range, else false

contains

public boolean contains(YearRange r)

Return true if (and only if) the given range is completely inside the range, inclusive.

Parameters:

r - range to check

Returns:

true if r is entirely in the range, else false

startOfRow

public boolean startOfRow(SafeIntYear y)

Return true, iff this year is the start of a row. (Year 1 is considered the start of that row.)

Returns:

true, iff this year is the start of a row

endOfRow

public boolean endOfRow(SafeIntYear y)

Return true, iff this year is the end of a row.

Returns:

true, iff this year is the end of a row

overlap

public int overlap(YearRange r)

Return the number of years overlap between this range and the given range.

Parameters:

r - range to compare

Returns:

number of years overlap

intersection

public YearRange intersection(YearRange r)

The intersection of this range with r. If they don't overlap, returns an empty range (1 - -1).

Parameters:

r - the range to intersect with this range

Returns:

the intersection of this and r

See Also:

union(org.tridas.io.util.YearRange)

union

public YearRange union(YearRange r)

The union of this range with r. Since there is no concept of "range with a gap" in Corina, it assumes they overlap.

Parameters:

r - the range to union with this range

Returns:

the union of this and r

See Also:

intersection(org.tridas.io.util.YearRange)

equals

public boolean equals(Object o)

Compare two ranges for equality.

Overrides:

equals in class Object

Parameters:

r - range to compare with this

Returns:

true, if the ranges are equal, else false

hashCode

public int hashCode()

A hash code for the Range. (Since I define equals(), I need to define hashCode().)

Overrides:

hashCode in class Object

Returns:

a hash code for this Range

compareTo

public int compareTo(Object o)

Compares this and o, for placing in fallback order. Fallback order sorts ranges by their ending year, latest to earliest, and then by their length, longest to shortest. (This is usually what people want when looking at bargraphs.)

Specified by:

compareTo in interface Comparable

Parameters:

o - Object to compare

Returns:

>0, ==0, or <0 if this is greater-than, equal-to, or less-than o

Throws:

ClassCastException - if o is not a Range