## 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 `TimeRange`s 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