org.tridas.io.util
Class SafeIntYear

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

All Implemented Interfaces:

Comparable

public final class SafeIntYear
extends Object
implements Comparable

A BC/AD calendar year in the form of a signed integer It normally acts similar to an integer, but skips the mythical "year 0".

In SafeIntYear math:

• -1 + 1 = 1
• 2 - 4 = -3

Years, like Numbers and Strings, are immutable, so they are not Cloneable (there's no reason for them to be).

Version:

$Id: Year.java 1671 2009-04-29 22:11:14Z lucasm $

Author:

Ken Harris <kbh7 at cornell dot edu>

Field Summary

static SafeIntYear

DEFAULT The default year: 1.

Constructor Summary

SafeIntYear()
Default constructor.

SafeIntYear(int x)
Constructor for ints.

SafeIntYear(int row, int col)
Constructor from (row,col) pair.

SafeIntYear(String s)
Constructor from String.

SafeIntYear(String s, boolean isAstronomical)
Constructor from String.

SafeIntYear(org.tridas.schema.Year x)
Construct a SafeIntYear from a native TridasYear.

Method Summary

SafeIntYear	add(int dy) Adds (or subtracts, for negative values) some number of years, and generates a new Year object.
int	column() Determines what column this year would be, if years were in a grid 10 wide, with the left column years ending in zero.
int	compareTo(Object o) Compares this and o.
SafeIntYear	cropToCentury()
int	diff(SafeIntYear y2) Calculate the number of years difference between two years.
boolean	equals(Object y2) Returns true if and only if this is equal to y2.
int	hashCode()
int	intValue() This method always throws UnsupportedOperationException.
boolean	isYearOne() Return true, iff this is year 1.
static SafeIntYear	max(SafeIntYear y1, SafeIntYear y2) The maximum (later) of two years.
static SafeIntYear	min(SafeIntYear y1, SafeIntYear y2) The minimum (earlier) of two years.
int	mod(int m) Computes this modulo m.
SafeIntYear	nextCentury()
int	row() Determines what row this year would be, if years were in a grid 10 wide, with the left column years ending in zero.
Integer	toAstronomicalInteger() Returns this SafeIntYear as an integer using the astronomical convention for BC years.
AstronomicalYear	toAstronomicalYear() Convert to an AstronomicalYear where 0 is valid and is equal to 1BC.
String	toString() Convert to a String.
org.tridas.schema.Year	toTridasYear(org.tridas.schema.DatingSuffix suffix)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT

public static final SafeIntYear DEFAULT

The default year: 1.

Constructor Detail

SafeIntYear

public SafeIntYear()

Default constructor. Uses DEFAULT as the year.

See Also:

DEFAULT

SafeIntYear

public SafeIntYear(int x)

Constructor for ints. Uses DEFAULT as the year if an invalid value is passed.

Parameters:

x - the year value, as an int

See Also:

DEFAULT

SafeIntYear

public SafeIntYear(org.tridas.schema.Year x)

Construct a SafeIntYear from a native TridasYear. The TridasYear allows the use of suffixes (BP, AD, BC) but does not know how to handle the 0BC/AD problem.

Parameters:

x -

SafeIntYear

public SafeIntYear(int row,
                   int col)

Constructor from (row,col) pair. Assumes 10-year rows. The column should always be between 0 and 9, inclusive.

Parameters:

row - the row; row 0 is the decade ending in year 9

col - the column; in row 0, year is the column

SafeIntYear

public SafeIntYear(String s)
            throws NumberFormatException

Constructor from String. No AD/BC; reads it like C's scanf(" %d ", &y) would.

Throws:

NumberFormatException - if the String cannot be parsed, or is equal to zero

See Also:

String

SafeIntYear

public SafeIntYear(String s,
                   boolean isAstronomical)
            throws NumberFormatException

Constructor from String. No AD/BC; reads it like C's scanf(" %d ", &y) would. If isAstronomical is true, then it subtracts 1 from all values which are <=0. i.e., -5 means 6 BC.

Throws:

NumberFormatException - if the String cannot be parsed

See Also:

String

Method Detail

toString

public String toString()

Convert to a String. No "AD"/"BC"; simply the integer value.

Overrides:

toString in class Object

Returns:

this year as a String

See Also:

String

intValue

public int intValue()

This method always throws UnsupportedOperationException. It's not implemented, and don't even think about implementing it yourself! It encourages being lazy and bypassing Year's methods to just deal with ints. And that defeats the whole purpose of having Years. So I'll just disallow it. You don't need it anyway. If you really need the int for some reason I can't imagine, you can always do Integer.parseInt(y.toString()). That way you know you're doing it to get the int, and not for imagined performance or convenience reasons.

Returns:

never returns

Throws:

UnsupportedOperationException - always!

toTridasYear

public org.tridas.schema.Year toTridasYear(org.tridas.schema.DatingSuffix suffix)

toAstronomicalYear

public AstronomicalYear toAstronomicalYear()

Convert to an AstronomicalYear where 0 is valid and is equal to 1BC.

Returns:

toAstronomicalInteger

public Integer toAstronomicalInteger()

Returns this SafeIntYear as an integer using the astronomical convention for BC years.

Returns:

isYearOne

public boolean isYearOne()

Return true, iff this is year 1. (This actually comes up fairly often.)

Returns:

true iff this is year 1

max

public static SafeIntYear max(SafeIntYear y1,
                              SafeIntYear y2)

The maximum (later) of two years.

Returns:

the later of two years

min

public static SafeIntYear min(SafeIntYear y1,
                              SafeIntYear y2)

The minimum (earlier) of two years.

Returns:

the earlier of two years

add

public SafeIntYear add(int dy)

Adds (or subtracts, for negative values) some number of years, and generates a new Year object.

Parameters:

dy - the number of years to add (subtract)

See Also:

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

diff

public int diff(SafeIntYear y2)

Calculate the number of years difference between two years. That is, there are this many years difference between this and y2; if they are equal, this number is zero.

Parameters:

y2 - the year to subtract

Returns:

the number of years difference between this and y2

See Also:

add(int)

mod

public int mod(int m)

Computes this modulo m. Always gives a positive result, even for negative numbers, so it is suitable for computing a grid position for a span of years.

Parameters:

m - base for modulo

Returns:

the year modulo m

row

public int row()

Determines what row this year would be, if years were in a grid 10 wide, with the left column years ending in zero. Row 0 is years 1 through 9.

Returns:

this year's row

See Also:

column()

column

public int column()

Determines what column this year would be, if years were in a grid 10 wide, with the left column years ending in zero. Works for BC years, also:

column()	0	1	2	3	4	5	6	7	8	9
Year	-10	-9	-8	-7	-6	-5	-4	-3	-2	-1
		1	2	3	4	5	6	7	8	9
	10	11	12	13	14	15	16	17	18	19

Returns:

this year's column

See Also:

row()

compareTo

public int compareTo(Object o)

Compares this and o.

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 Year

See Also:

Comparable

equals

public boolean equals(Object y2)

Returns true if and only if this is equal to y2.

Overrides:

equals in class Object

Parameters:

y2 - the year to compare this to

Returns:

true if this is equal to y2, else false

hashCode

public int hashCode()

Overrides:

hashCode in class Object

cropToCentury

public SafeIntYear cropToCentury()

nextCentury

public SafeIntYear nextCentury()