com.rbnb.api
Class TimeRange

java.lang.Object
  com.rbnb.api.TimeRange

All Implemented Interfaces:

Serializable, Cloneable

public final class TimeRange
extends Object

The range of times that applies to the data of an Rmap.

A TimeRange consists of:

• A list of one or more time values, and
• A duration greater than or equal to 0.

The number of time values in the TimeRange and the number of data points must satisfy one of the following three cases:

1. number of times = number of points,
2. one time and any number of points, or
3. any number of times and one point.

When the number of times equals the number of points, the time for a point is equal to the time corresponding to the point.

When there is a single time and a number of points larger than one, the time for a point is equal to:

    time + (point #)/(number of points)

When there are multiple times and a single data point, all of the times apply to the point. This is usually used when the "point" of data is is actually a data pool. The children of the data pool are inheriting the times.

All data points have a duration that is either:

• The duration of the TimeRange (when there is just a single time in the TimeRange), or
• The duration of the TimeRange divided by the number of data points.

TimeRanges can inherit time values and duration from other TimeRanges. The way that the inheritance works is described in the documentation for Rmaps.

Since:

V2.0

See Also:

Rmap, Serialized Form

Author:

Ian Brown

Version:

05/19/2005

Field Summary

static double	INHERIT_DURATION Duration value is inherited.
static double[]	INHERIT_TIMES Time values are inherited.
static TimeRange	SERVER_TOD server time of day.

Constructor Summary

TimeRange()
Class constructor.

TimeRange(double timeI)
Class constructor to build a TimeRange for a single time and an inherited duration.

TimeRange(double[] ptimesI)
Class constructor to build a TimeRange from an array of times and an inherited duration.

TimeRange(double[] ptimesI, double durationI)
Class constructor to build a TimeRange from an array of times and a duration.

TimeRange(double startI, double durationI)
Class constructor to build a TimeRange from a single time and duration.

Method Summary

Object	clone() Clones this TimeRange.
int	compareTo(TimeRange otherI) Compares this TimeRange to the input one.
int	copyTimes(int nPointsI, double[] timeI, int startAtI) Copies the times for all of the points in this range to an array.
boolean	extend(int myPointsI, TimeRange otherI, int oPointsI) Extends the range of this TimeRange by adding the input TimeRange to the end.
double	getDuration() Gets the duration.
double[]	getLimits() Gets the minimum and maximum times of this TimeRange.
int	getNptimes() Gets the number of point times in a TimeRange.
double	getPointTime(int pointI, int nPointsI) Gets the time value for a particular point.
double[]	getPtimes() Gets the individual point times array.
double	getTime() Gets the time of the range.
boolean	isInclusive() Inclusive of both ends of range?
void	nullify() Nullifies this TimeRange.
void	set(double timeI) Sets the time of the range and clears the duration so that it gets inherited.
void	set(double[] ptimesI) Sets the individual point times for the range and clears the duration so that it gets inherited.
void	set(double[] ptimesI, double durationI) Sets the individual point times for the range and the duration.
void	set(double startI, double durationI) Sets the time and duration of the range.
void	setDuration(double durationI) Sets the duration.
void	setInclusive(boolean inclusiveI) Sets the inclusive flag.
void	setPtimes(double[] ptimesI) Sets the individual point times array.
String	toString() Gets a displayable string representation of this TimeRange.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INHERIT_DURATION

public static final double INHERIT_DURATION

Duration value is inherited.

Since:

V2.0

See Also:

Constant Field Values

Author:

Ian Brown

Version:

04/06/2001

INHERIT_TIMES

public static final double[] INHERIT_TIMES

Time values are inherited.

Since:

V2.0

Author:

Ian Brown

Version:

01/23/2001

SERVER_TOD

public static final TimeRange SERVER_TOD

server time of day.

Since:

V2.0

Author:

Ian Brown

Version:

10/23/2002

Constructor Detail

TimeRange

public TimeRange()

Class constructor.

Since:

V2.0

Author:

Ian Brown

Version:

01/09/2001

TimeRange

public TimeRange(double timeI)

Class constructor to build a TimeRange for a single time and an inherited duration.

Parameters:

timeI - the time.

Since:

V2.0

See Also:

TimeRange(double,double), TimeRange(double[]), TimeRange(double[],double)

Author:

Ian Brown

Version:

11/06/2002

TimeRange

public TimeRange(double startI,
                 double durationI)

Class constructor to build a TimeRange from a single time and duration.

Parameters:

startI - the time.

durationI - the duration.

Since:

V2.0

See Also:

TimeRange(double), TimeRange(double[]), TimeRange(double[],double)

Author:

Ian Brown

Version:

11/06/2002

TimeRange

public TimeRange(double[] ptimesI)

Class constructor to build a TimeRange from an array of times and an inherited duration.

Parameters:

ptimesI - the individual point times.

Since:

V2.0

See Also:

TimeRange(double), TimeRange(double,double), TimeRange(double[],double)

Author:

Ian Brown

Version:

11/06/2002

TimeRange

public TimeRange(double[] ptimesI,
                 double durationI)

Class constructor to build a TimeRange from an array of times and a duration.

Parameters:

ptimesI - the individual point times.

Since:

V2.0

See Also:

TimeRange(double), TimeRange(double,double), TimeRange(double[])

Author:

Ian Brown

Version:

11/06/2002

Method Detail

clone

public final Object clone()

Clones this TimeRange.

This method clones the ptimes array.

Returns:

the clone.

Since:

V2.0

Author:

Ian Brown

Version:

04/25/2001

compareTo

public final int compareTo(TimeRange otherI)

Compares this TimeRange to the input one.

The only way that two TimeRanges can be considered "equal" is if they have exactly the same values. Otherwise, one is always considered to come "before" the other. The comparison depends on exactly what fields are set and how they are set in the two TimeRanges. The rules are:

Compare the times of the two TimeRanges in order. If any of the times for one is less than the corresponding time for for the other, then that TimeRange is less than the other. If one TimeRange runs out of times before the other does, then it is less than the other.

If the duration for one TimeRange is inherited or less than the other, then that TimeRange is less than the other.

Parameters:

otherI - the other TimeRange.

Returns:

the results of the comparison:

<0 if this TimeRange is less than the input,

=0 if the two TimeRanges are equal, or

>0 if this TimeRange is greater than the input.

Since:

V2.0

Author:

Ian Brown

Version:

10/25/2002

copyTimes

public final int copyTimes(int nPointsI,
                           double[] timeI,
                           int startAtI)

Copies the times for all of the points in this range to an array.

Parameters:

nPointsI - the number of data points that the TimeRange describes. This can be one of the following:

1. Equal to the value returned by getNptimes(),
2. Any positive value if getNptimes() is 1, or
3. 0, in which case it is assumed to be equal to getNptimes().

timeI - the time array to copy the points into.

startAtI - the starting index into the time array.

Returns:

the number of points copied.

Throws:

IllegalArgumentException - thrown if:

• nPointsI < 0, or
• nPointsI != getNptimes() and the latter is not equal to 1.

Since:

V2.0

Author:

Ian Brown

Version:

08/30/2002

extend

public final boolean extend(int myPointsI,
                            TimeRange otherI,
                            int oPointsI)

Extends the range of this TimeRange by adding the input TimeRange to the end.

This method determines whether or not the input TimeRange is compatible with this one. To be compatible, the two TimeRanges must satisfy the one of the following:

• both TimeRanges must have multiple start times and equal durations, or
• both TimeRanges must have a single start time and a duration such that the start time of the input TimeRange is equal to the start time + duration of this TimeRange and the interval between points in the two TimeRanges are equal.

Parameters:

myPointsI - the number of data points represented by this TimeRange.

otherI - the other TimeRange.

oPointsI - the number of data points represented by the input TimeRange.

Returns:

were the TimeRanges compatible? If this is false, then this TimeRange is left unchanged, otherwise this TimeRange is extended to include the input.

Since:

V2.0

Author:

Ian Brown

Version:

11/06/2002

getDuration

public final double getDuration()

Gets the duration.

Returns:

the duration.

Since:

V2.0

See Also:

set(double,double), set(double[],double), setDuration(double)

Author:

Ian Brown

Version:

05/22/2001

getLimits

public final double[] getLimits()

Gets the minimum and maximum times of this TimeRange.

Returns:

the minimum and maximum times of this TimeRange as an array.

Since:

V2.0

Author:

Ian Brown

Version:

11/07/2001

getNptimes

public final int getNptimes()

Gets the number of point times in a TimeRange.

Returns:

the number of point times.

Since:

V2.0

See Also:

set(double), set(double,double), set(double[]), set(double[],double)

Author:

Ian Brown

Version:

05/22/2001

getPointTime

public final double getPointTime(int pointI,
                                 int nPointsI)

Gets the time value for a particular point.

The time value equals one of:

1. The time at the point index, or
2. getTime() + getDuration()*pointI/nPointsI.

Parameters:

pointI - the desired point.

nPointsI - the number of data points that the TimeRange describes. This can be one of the following:

1. Equal to the value returned by getNptimes(),
2. Any positive value if getNptimes() is 1, or
3. 0, in which case it is assumed to be equal to getNptimes().

Returns:

the time.

Throws:

IllegalStateException - thrown if getNptimes() is zero.

IllegalArgumentException - thrown if:

• nPointsI < 0,
• nPointsI != getNptimes() and the latter is not equal to 1, or
• 0 <= pointI < nPointsI is not true.

Since:

V2.0

Author:

Ian Brown

Version:

01/25/2001

getPtimes

public final double[] getPtimes()

Gets the individual point times array.

Returns:

the point times array.

Since:

V2.0

See Also:

set(double[]), set(double[],double), setPtimes(double[])

Author:

Ian Brown

Version:

05/22/2001

getTime

public final double getTime()

Gets the time of the range.

Returns:

the time.

Since:

V2.0

Author:

Ian Brown

Version:

04/12/2002

isInclusive

public boolean isInclusive()

Inclusive of both ends of range?

If the duration of the TimeRange is zero (0), then the range is inclusive.

Returns:

does this TimeRange include both the start and end time, or just the one nearest the reference of a request?

Since:

V2.0

Author:

Ian Brown

Version:

10/28/2002

nullify

public final void nullify()

Nullifies this TimeRange.

This method ensures that all pointers in this DataBlock are cleared, reducing the effort needed by the garbage collector to clean it up.

Since:

V2.2

Author:

Ian Brown

Version:

07/30/2003

set

public final void set(double timeI)

Sets the time of the range and clears the duration so that it gets inherited.

Parameters:

timeI - the time.

Since:

V2.0

See Also:

getTime(), set(double,double), set(double[]), set(double[],double)

Author:

Ian Brown

Version:

11/30/2000

set

public final void set(double startI,
                      double durationI)

Sets the time and duration of the range.

Parameters:

startI - the time.

durationI - the duration.

Throws:

IllegalArgumentException - thrown if the duration is negative and is not INHERIT_DURATION.

Since:

V2.0

See Also:

getTime(), getDuration(), set(double), set(double[]), set(double[],double), setDuration(double), setPtimes(double[])

Author:

Ian Brown

Version:

11/14/2003

set

public final void set(double[] ptimesI)

Sets the individual point times for the range and clears the duration so that it gets inherited.

Parameters:

ptimesI - the individual point times.

Since:

V2.0

See Also:

getNptimes(), getPtimes(), set(double), set(double,double), set(double[],double), setDuration(double), setPtimes(double[])

Author:

Ian Brown

Version:

11/30/2000

set

public final void set(double[] ptimesI,
                      double durationI)

Sets the individual point times for the range and the duration.

Parameters:

ptimesI - the individual point times.

durationI - the duration.

Throws:

IllegalArgumentException - thrown if the duration is negative and is not INHERIT_DURATION.

Since:

V2.0

See Also:

getDuration(), getNptimes(), getPtimes(), set(double), set(double,double), set(double[])

Author:

Ian Brown

Version:

11/14/2003

setDuration

public final void setDuration(double durationI)

Sets the duration.

Parameters:

durationI - the new duration.

Since:

V2.0

See Also:

getDuration()

Author:

Ian Brown

Version:

05/31/2001

setInclusive

public final void setInclusive(boolean inclusiveI)

Sets the inclusive flag.

Parameters:

inclusiveI - include both ends of the range?

Since:

V2.0

See Also:

isInclusive()

Author:

Ian Brown

Version:

11/06/2002

setPtimes

public final void setPtimes(double[] ptimesI)

Sets the individual point times array.

Parameters:

ptimesI - the new point times array.

Since:

V2.0

See Also:

getPtimes()

Author:

Ian Brown

Version:

05/31/2001

toString

public String toString()

Gets a displayable string representation of this TimeRange.

Overrides:

toString in class Object

Returns:

the string representation.

Since:

V2.0

Author:

Ian Brown

Version:

01/27/2003