com.jstatcom.ts
Class TSDate

java.lang.Object
  com.jstatcom.ts.TSDate

All Implemented Interfaces:

java.lang.Comparable

public final class TSDate
extends java.lang.Object
implements java.lang.Comparable

Representation of a date for an observation of a time series. It defines a mainPeriod, a subPeriod and a subPeriodicity. The subPeriodicity quantifies the number of sub periods which constitute one main period. It is also called frequency. A range of two TSDate objects is represented by the TSDateRange class.

This class is immutable.

Author:

A. Benkwitz, Markus Kraetzig

See Also:

TSDateRange

Constructor Summary

TSDate()
Default constructor creates a standard TSDate object with string representation 1.

TSDate(double newDate, int newSubPeriodicity)
Creates a TSDate with a double coded date and a sub periodicity.

TSDate(int mainPeriod, int subPeriod, int subPeriodicity)
Creates a TSDate object from a main period, a sub period, and a sub periodicity.

Method Summary

TSDate	addPeriods(int n) Adds n periods to a copy of the TSDate object.
int	compareTo(java.lang.Object o) Compares two TSDate objects.
double	doubleValue() Returns this date in number form.
boolean	equals(java.lang.Object o) Overrides equals to provide logical comparison of two different TSDate objects.
java.util.Date	getDate() Currently only implemented for daily dates, otherwise an Exception is thrown.
int	hashCode() Overrides hashCode, because equals was overwritten.
int	mainPeriod() Returns the main period of this date.
java.lang.String	printNice() Gets a nicely formatted string representing this date.
java.lang.String	printShort() Gets a formatted string representing this date that is very short.
int	subPeriod() Returns the sub period of this date.
int	subPeriodFor(int n) Gets the sub period is reached when n periods are added to this date.
int	subPeriodFormat() Returns the sub period format for the double representation of this date.
int	subPeriodicity() Returns the sub periodicity of this date.
java.lang.String[]	timeAxisStringArray(int t) This method creates a time axis starting from this date as an array of Strings of length t, for example {"1960 Q1", "1960 Q2", ..., "1982 Q4"}.
java.lang.String	toString() Returns a string representation of this TSDate.
static TSDate	valueOf(java.lang.String exp) Static initializer that creates a TSDate from a string expression.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TSDate

public TSDate()

Default constructor creates a standard TSDate object with string representation 1.

TSDate

public TSDate(double newDate,
              int newSubPeriodicity)

Creates a TSDate with a double coded date and a sub periodicity.

Parameters:

newDate - double coded date.

newSubPeriodicity - maximum number of sub periods.

Throws:

java.lang.IllegalArgumentException - if subPeriodicity < 1 or subPeriod < 1 or subPeriodicity < subPeriod

TSDate

public TSDate(int mainPeriod,
              int subPeriod,
              int subPeriodicity)

Creates a TSDate object from a main period, a sub period, and a sub periodicity.

Parameters:

mainPeriod - the main period (left of the decimal point).

subPeriod - the sub period ('right' of the decimal point).

subPeriodicity - the sub periodicity.

Throws:

java.lang.IllegalArgumentException - if (subPeriodicity < 1 || subPeriod < 1 || subPeriodicity < subPeriod)

Method Detail

addPeriods

public TSDate addPeriods(int n)

Adds n periods to a copy of the TSDate object.

Parameters:

n - number of periods to be added, can be negative

Returns:

new TSDate with n periods added

compareTo

public int compareTo(java.lang.Object o)

Compares two TSDate objects.

Specified by:

compareTo in interface java.lang.Comparable

Returns:

0 if they are equal, otherwise number of periods between the two dates, which is < 0 if (TSDate) o is earlier than this

Throws:

java.lang.ClassCastException - if o is not a TSDate

java.lang.IllegalArgumentException - if sub periodicities do not match, because there is no meaningful way to compare the dates

doubleValue

public double doubleValue()

Returns this date in number form.

Returns:

double representation of this TSDate

equals

public boolean equals(java.lang.Object o)

Overrides equals to provide logical comparison of two different TSDate objects.

Overrides:

equals in class java.lang.Object

Parameters:

o - object to compare with

Returns:

true if mainPeriod, subPeriod and subPeriodicity are the same, false otherwise

mainPeriod

public int mainPeriod()

Returns the main period of this date.

Returns:

the main period (left of the decimal point):

subPeriod

public int subPeriod()

Returns the sub period of this date.

Returns:

sub period, is always within [1, subPeriodicity]

subPeriodFor

public int subPeriodFor(int n)

Gets the sub period is reached when n periods are added to this date.

Parameters:

n - number of periods to be added, can be negative

Returns:

the sub period as int

subPeriodFormat

public int subPeriodFormat()

Returns the sub period format for the double representation of this date. This number acts as a place holder for the digits of the sub period. If subPeriodicity < 10, this number returns 10, if 10 <= subPeriodicity < 100, this number returns 100 and so on. If one multiplies the double coded date with the sub period format, one always gets a value that is equal to an integer, because the decimal digits vanish.

Returns:

the sub period format

subPeriodicity

public int subPeriodicity()

Returns the sub periodicity of this date. The subPeriodicity quantifies the number of sub periods which constitute one main period.

Returns:

the sub periodicity

hashCode

public int hashCode()

Overrides hashCode, because equals was overwritten. The algorithm was taken from (Joshua Bloch, "Effective Java", Item 8) .

Overrides:

hashCode in class java.lang.Object

Returns:

hash code

printNice

public java.lang.String printNice()

Gets a nicely formatted string representing this date. Unlike the toString method, the resulting string is not necessarily a valid argument for the valueOf method. Especially daily data is printed differently with the weekday and without "(5)" or "(7)".

Returns:

formatted string

printShort

public java.lang.String printShort()

Gets a formatted string representing this date that is very short. Unlike the toString method, the resulting string is not necessarily a valid argument for the valueOf method. Especially daily data is printed differently with the weekday and without "(5)" or "(7)".

Returns:

formatted string

timeAxisStringArray

public java.lang.String[] timeAxisStringArray(int t)

This method creates a time axis starting from this date as an array of Strings of length t, for example {"1960 Q1", "1960 Q2", ..., "1982 Q4"}.

Parameters:

t - int Length of the time axis.

Returns:

String[] time axis with dates for every time index

Throws:

java.lang.IllegalArgumentException - if t < 1

getDate

public java.util.Date getDate()

Currently only implemented for daily dates, otherwise an Exception is thrown. Assembles a java.util.Date object from this. The returned date always denotes the start of this date.

Returns:

date

Throws:

java.lang.IllegalStateException - if this does not represent daily data

toString

public java.lang.String toString()

Returns a string representation of this TSDate. A TSDate object can be constructed from a string using the TSDateParser or respective the TSDate.valueOf initializer. Do not use for comparisons, but use equals instead.

Overrides:

toString in class java.lang.Object

Returns:

String representation of this object.

See Also:

TSDateParser

valueOf

public static TSDate valueOf(java.lang.String exp)

Static initializer that creates a TSDate from a string expression. The format of the string is based on the following rules:

• XX x"/"y, for example 1960 1/1 is recognized for arbitrary sub periodicities with mainPeriod=XX, subPeriod=x, subPeriodicity=y
• XX ["M","m"]x, for example 1960 M1 is recognized as mainPeriod=XX, subPeriod=x, subPeriodicity=12 (monthly)
• XX ["Q","q"]x, for example 1960 Q1 is recognized as mainPeriod=XX, subPeriod=x, subPeriodicity=4 (quarterly)
• XX ["I", "II"], for example 1960 I is recognized as mainPeriod=XX, subPeriod=1 or 2, subPeriodicity=2 (half yearly)
• XX , for example 1960 is recognized as mainPeriod=XX, subPeriod=1, subPeriodicity=1 (yearly)

Daily Data:
Daily data is a special case. It is always assumed by this class when the periodicity is either 5 (working days) or 7 (all days). It can be specified by using the default date format for the US locale, followed by "(5)" or "(7)", for example:

1/1/73 (5)
10/12/2004 (7)

If a 5 day week is specified and the date falls on a weekend, it is automatically set to the following monday without further notice.

Parameters:

exp - expression to parse to a date

Returns:

a TSDate object created from exp

Throws:

java.lang.IllegalArgumentException - if object could not be constructed from given string or if exp == null

See Also:

TSDateParser