## org.jfree.data.time
Class TimeSeries

    java.lang.Object
      org.jfree.data.general.Series
          org.jfree.data.time.TimeSeries

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable

    public class TimeSeries

extends Series
implements java.lang.Cloneable, java.io.Serializable

Represents a sequence of zero or more data items in the form (period, value).

See Also:
  Serialized Form

Field Summary
`protected java.util.List` `data` The list of data items in the series.
`protected static java.lang.String` `DEFAULT_DOMAIN_DESCRIPTION` Default value for the domain description.
`protected static java.lang.String` `DEFAULT_RANGE_DESCRIPTION` Default value for the range description.
`protected java.lang.Class` `timePeriodClass` The type of period for the data.

Constructor Summary
`TimeSeries(java.lang.Comparable name)` Creates a new (empty) time series.
`TimeSeries(java.lang.Comparable name, java.lang.Class timePeriodClass)` Creates a new (empty) time series with the specified name and class of `RegularTimePeriod`.
`TimeSeries(java.lang.Comparable name, java.lang.String domain, java.lang.String range, java.lang.Class timePeriodClass)` Creates a new time series that contains no data.

Method Summary
`void` `add(RegularTimePeriod period, double value)` Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.
`void` `add(RegularTimePeriod period, double value, boolean notify)` Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.
`void` `add(RegularTimePeriod period, java.lang.Number value)` Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.
`void` `add(RegularTimePeriod period, java.lang.Number value, boolean notify)` Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.
`void` `add(TimeSeriesDataItem item)` Adds a data item to the series and sends a `SeriesChangeEvent` to all registered listeners.
`void` `add(TimeSeriesDataItem item, boolean notify)` Adds a data item to the series and sends a `SeriesChangeEvent` to all registered listeners.
`TimeSeries` `addAndOrUpdate(TimeSeries series)` Adds or updates data from one series to another.
`TimeSeriesDataItem` `addOrUpdate(RegularTimePeriod period, double value)` Adds or updates an item in the times series and sends a `SeriesChangeEvent` to all registered listeners.
`TimeSeriesDataItem` `addOrUpdate(RegularTimePeriod period, java.lang.Number value)` Adds or updates an item in the times series and sends a `SeriesChangeEvent` to all registered listeners.
`void` `clear()` Removes all data items from the series and sends a `SeriesChangeEvent` to all registered listeners.
`java.lang.Object` `clone()` Returns a clone of the time series.
`TimeSeries` `createCopy(int start, int end)` Creates a new timeseries by copying a subset of the data in this time series.
`TimeSeries` `createCopy(RegularTimePeriod start, RegularTimePeriod end)` Creates a new timeseries by copying a subset of the data in this time series.
`void` `delete(int start, int end)` Deletes data from start until end index (end inclusive).
`void` `delete(RegularTimePeriod period)` Deletes the data item for the given time period and sends a `SeriesChangeEvent` to all registered listeners.
`boolean` `equals(java.lang.Object object)` Tests the series for equality with an arbitrary object.
`TimeSeriesDataItem` `getDataItem(int index)` Returns a data item for the series.
`TimeSeriesDataItem` `getDataItem(RegularTimePeriod period)` Returns the data item for a specific period.
`java.lang.String` `getDomainDescription()` Returns the domain description.
`int` `getIndex(RegularTimePeriod period)` Returns the index for the item (if any) that corresponds to a time period.
`int` `getItemCount()` Returns the number of items in the series.
`java.util.List` `getItems()` Returns the list of data items for the series (the list contains `TimeSeriesDataItem` objects and is unmodifiable).
`long` `getMaximumItemAge()` Returns the maximum item age (in time periods) for the series.
`int` `getMaximumItemCount()` Returns the maximum number of items that will be retained in the series.
`RegularTimePeriod` `getNextTimePeriod()` Returns a time period that would be the next in sequence on the end of the time series.
`java.lang.String` `getRangeDescription()` Returns the range description.
`RegularTimePeriod` `getTimePeriod(int index)` Returns the time period at the specified index.
`java.lang.Class` `getTimePeriodClass()` Returns the time period class for this series.
`java.util.Collection` `getTimePeriods()` Returns a collection of all the time periods in the time series.
`java.util.Collection` `getTimePeriodsUniqueToOtherSeries(TimeSeries series)` Returns a collection of time periods in the specified series, but not in this series, and therefore unique to the specified series.
`java.lang.Number` `getValue(int index)` Returns the value at the specified index.
`java.lang.Number` `getValue(RegularTimePeriod period)` Returns the value for a time period.
`int` `hashCode()` Returns a hash code value for the object.
`void` `removeAgedItems(boolean notify)` Age items in the series.
`void` `removeAgedItems(long latest, boolean notify)` Age items in the series.
`void` `setDomainDescription(java.lang.String description)` Sets the domain description and sends a `PropertyChangeEvent` (with the property name `Domain`) to all registered property change listeners.
`void` `setMaximumItemAge(long periods)` Sets the number of time units in the 'history' for the series.
`void` `setMaximumItemCount(int maximum)` Sets the maximum number of items that will be retained in the series.
`void` `setRangeDescription(java.lang.String description)` Sets the range description and sends a `PropertyChangeEvent` (with the property name `Range`) to all registered listeners.
`void` `update(int index, java.lang.Number value)` Updates (changes) the value of a data item.
`void` `update(RegularTimePeriod period, java.lang.Number value)` Updates (changes) the value for a time period.

Methods inherited from class org.jfree.data.general.Series
`addChangeListener, addPropertyChangeListener, firePropertyChange, fireSeriesChanged, getDescription, getKey, getNotify, isEmpty, notifyListeners, removeChangeListener, removePropertyChangeListener, setDescription, setKey, setNotify`

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_DOMAIN_DESCRIPTION

    protected static final java.lang.String DEFAULT_DOMAIN_DESCRIPTION

  Default value for the domain description.

  See Also:
    Constant Field Values

### DEFAULT_RANGE_DESCRIPTION

    protected static final java.lang.String DEFAULT_RANGE_DESCRIPTION

  Default value for the range description.

  See Also:
    Constant Field Values

### timePeriodClass

    protected java.lang.Class timePeriodClass

  The type of period for the data.

### data

    protected java.util.List data

  The list of data items in the series.

Constructor Detail

### TimeSeries

    public TimeSeries(java.lang.Comparable name)

  Creates a new (empty) time series. By default, a daily time series is created. Use one of the other constructors if you require a different time period.

  Parameters:
    `name` - the series name (`null` not permitted).

### TimeSeries

    public TimeSeries(java.lang.Comparable name,
                      java.lang.Class timePeriodClass)

  Creates a new (empty) time series with the specified name and class of `RegularTimePeriod`.

  Parameters:
    `name` - the series name (`null` not permitted).
    `timePeriodClass` - the type of time period (`null` not permitted).

### TimeSeries

    public TimeSeries(java.lang.Comparable name,
                      java.lang.String domain,
                      java.lang.String range,
                      java.lang.Class timePeriodClass)

  Creates a new time series that contains no data.

  Descriptions can be specified for the domain and range. One situation where this is helpful is when generating a chart for the time series - axis labels can be taken from the domain and range description.

  Parameters:
    `name` - the name of the series (`null` not permitted).
    `domain` - the domain description (`null` permitted).
    `range` - the range description (`null` permitted).
    `timePeriodClass` - the type of time period (`null` not permitted).

Method Detail

### getDomainDescription

    public java.lang.String getDomainDescription()

  Returns the domain description.

  Returns:
    The domain description (possibly `null`).
  See Also:
    `setDomainDescription(String)`

### setDomainDescription

    public void setDomainDescription(java.lang.String description)

  Sets the domain description and sends a `PropertyChangeEvent` (with the property name `Domain`) to all registered property change listeners.

  Parameters:
    `description` - the description (`null` permitted).
  See Also:
    `getDomainDescription()`

### getRangeDescription

    public java.lang.String getRangeDescription()

  Returns the range description.

  Returns:
    The range description (possibly `null`).
  See Also:
    `setRangeDescription(String)`

### setRangeDescription

    public void setRangeDescription(java.lang.String description)

  Sets the range description and sends a `PropertyChangeEvent` (with the property name `Range`) to all registered listeners.

  Parameters:
    `description` - the description (`null` permitted).
  See Also:
    `getRangeDescription()`

### getItemCount

    public int getItemCount()

  Returns the number of items in the series.

  Specified by:
    `getItemCount` in class `Series`
  Returns:
    The item count.

### getItems

    public java.util.List getItems()

  Returns the list of data items for the series (the list contains `TimeSeriesDataItem` objects and is unmodifiable).

  Returns:
    The list of data items.

### getMaximumItemCount

    public int getMaximumItemCount()

  Returns the maximum number of items that will be retained in the series. The default value is `Integer.MAX_VALUE`.

  Returns:
    The maximum item count.
  See Also:
    `setMaximumItemCount(int)`

### setMaximumItemCount

    public void setMaximumItemCount(int maximum)

  Sets the maximum number of items that will be retained in the series. If you add a new item to the series such that the number of items will exceed the maximum item count, then the FIRST element in the series is automatically removed, ensuring that the maximum item count is not exceeded.

  Parameters:
    `maximum` - the maximum (requires >= 0).
  See Also:
    `getMaximumItemCount()`

### getMaximumItemAge

    public long getMaximumItemAge()

  Returns the maximum item age (in time periods) for the series.

  Returns:
    The maximum item age.
  See Also:
    `setMaximumItemAge(long)`

### setMaximumItemAge

    public void setMaximumItemAge(long periods)

  Sets the number of time units in the 'history' for the series. This provides one mechanism for automatically dropping old data from the time series. For example, if a series contains daily data, you might set the history count to 30. Then, when you add a new data item, all data items more than 30 days older than the latest value are automatically dropped from the series.

  Parameters:
    `periods` - the number of time periods.
  See Also:
    `getMaximumItemAge()`

### getTimePeriodClass

    public java.lang.Class getTimePeriodClass()

  Returns the time period class for this series.

  Only one time period class can be used within a single series (enforced). If you add a data item with a `Year` for the time period, then all subsequent data items must also have a `Year` for the time period.

  Returns:
    The time period class (never `null`).

### getDataItem

    public TimeSeriesDataItem getDataItem(int index)

  Returns a data item for the series.

  Parameters:
    `index` - the item index (zero-based).
  Returns:
    The data item.
  See Also:
    `getDataItem(RegularTimePeriod)`

### getDataItem

    public TimeSeriesDataItem getDataItem(RegularTimePeriod period)

  Returns the data item for a specific period.

  Parameters:
    `period` - the period of interest (`null` not allowed).
  Returns:
    The data item matching the specified period (or `null` if there is no match).
  See Also:
    `getDataItem(int)`

### getTimePeriod

    public RegularTimePeriod getTimePeriod(int index)

  Returns the time period at the specified index.

  Parameters:
    `index` - the index of the data item.
  Returns:
    The time period.

### getNextTimePeriod

    public RegularTimePeriod getNextTimePeriod()

  Returns a time period that would be the next in sequence on the end of the time series.

  Returns:
    The next time period.

### getTimePeriods

    public java.util.Collection getTimePeriods()

  Returns a collection of all the time periods in the time series.

  Returns:
    A collection of all the time periods.

### getTimePeriodsUniqueToOtherSeries

    public java.util.Collection getTimePeriodsUniqueToOtherSeries(TimeSeries series)

  Returns a collection of time periods in the specified series, but not in this series, and therefore unique to the specified series.

  Parameters:
    `series` - the series to check against this one.
  Returns:
    The unique time periods.

### getIndex

    public int getIndex(RegularTimePeriod period)

  Returns the index for the item (if any) that corresponds to a time period.

  Parameters:
    `period` - the time period (`null` not permitted).
  Returns:
    The index.

### getValue

    public java.lang.Number getValue(int index)

  Returns the value at the specified index.

  Parameters:
    `index` - index of a value.
  Returns:
    The value (possibly `null`).

### getValue

    public java.lang.Number getValue(RegularTimePeriod period)

  Returns the value for a time period. If there is no data item with the specified period, this method will return `null`.

  Parameters:
    `period` - time period (`null` not permitted).
  Returns:
    The value (possibly `null`).

### add

    public void add(TimeSeriesDataItem item)

  Adds a data item to the series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `item` - the (timeperiod, value) pair (`null` not permitted).

### add

    public void add(TimeSeriesDataItem item,
                    boolean notify)

  Adds a data item to the series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `item` - the (timeperiod, value) pair (`null` not permitted).
    `notify` - notify listeners?

### add

    public void add(RegularTimePeriod period,
                    double value)

  Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `period` - the time period (`null` not permitted).
    `value` - the value.

### add

    public void add(RegularTimePeriod period,
                    double value,
                    boolean notify)

  Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `period` - the time period (`null` not permitted).
    `value` - the value.
    `notify` - notify listeners?

### add

    public void add(RegularTimePeriod period,
                    java.lang.Number value)

  Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `period` - the time period (`null` not permitted).
    `value` - the value (`null` permitted).

### add

    public void add(RegularTimePeriod period,
                    java.lang.Number value,
                    boolean notify)

  Adds a new data item to the series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `period` - the time period (`null` not permitted).
    `value` - the value (`null` permitted).
    `notify` - notify listeners?

### update

    public void update(RegularTimePeriod period,
                       java.lang.Number value)

  Updates (changes) the value for a time period. Throws a `SeriesException` if the period does not exist.

  Parameters:
    `period` - the period (`null` not permitted).
    `value` - the value (`null` permitted).

### update

    public void update(int index,
                       java.lang.Number value)

  Updates (changes) the value of a data item.

  Parameters:
    `index` - the index of the data item.
    `value` - the new value (`null` permitted).

### addAndOrUpdate

    public TimeSeries addAndOrUpdate(TimeSeries series)

  Adds or updates data from one series to another. Returns another series containing the values that were overwritten.

  Parameters:
    `series` - the series to merge with this.
  Returns:
    A series containing the values that were overwritten.

### addOrUpdate

    public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period,
                                          double value)

  Adds or updates an item in the times series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `period` - the time period to add/update (`null` not permitted).
    `value` - the new value.
  Returns:
    A copy of the overwritten data item, or `null` if no item was overwritten.

### addOrUpdate

    public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period,
                                          java.lang.Number value)

  Adds or updates an item in the times series and sends a `SeriesChangeEvent` to all registered listeners.

  Parameters:
    `period` - the time period to add/update (`null` not permitted).
    `value` - the new value (`null` permitted).
  Returns:
    A copy of the overwritten data item, or `null` if no item was overwritten.

### removeAgedItems

    public void removeAgedItems(boolean notify)

  Age items in the series. Ensure that the timespan from the youngest to the oldest record in the series does not exceed maximumItemAge time periods. Oldest items will be removed if required.

  Parameters:
    `notify` - controls whether or not a `SeriesChangeEvent` is sent to registered listeners IF any items are removed.

### removeAgedItems

    public void removeAgedItems(long latest,
                                boolean notify)

  Age items in the series. Ensure that the timespan from the supplied time to the oldest record in the series does not exceed history count. oldest items will be removed if required.

  Parameters:
    `latest` - the time to be compared against when aging data (specified in milliseconds).
    `notify` - controls whether or not a `SeriesChangeEvent` is sent to registered listeners IF any items are removed.

### clear

    public void clear()

  Removes all data items from the series and sends a `SeriesChangeEvent` to all registered listeners.

### delete

    public void delete(RegularTimePeriod period)

  Deletes the data item for the given time period and sends a `SeriesChangeEvent` to all registered listeners. If there is no item with the specified time period, this method does nothing.

  Parameters:
    `period` - the period of the item to delete (`null` not permitted).

### delete

    public void delete(int start,
                       int end)

  Deletes data from start until end index (end inclusive).

  Parameters:
    `start` - the index of the first period to delete.
    `end` - the index of the last period to delete.

### clone

    public java.lang.Object clone()
                           throws java.lang.CloneNotSupportedException

  Returns a clone of the time series.

  Notes:

  - no need to clone the domain and range descriptions, since String object is immutable;
  - we pass over to the more general method clone(start, end).

  Overrides:
    `clone` in class `Series`
  Returns:
    A clone of the time series.
  Throws:
    `java.lang.CloneNotSupportedException` - not thrown by this class, but subclasses may differ.

### createCopy

    public TimeSeries createCopy(int start,
                                 int end)
                          throws java.lang.CloneNotSupportedException

  Creates a new timeseries by copying a subset of the data in this time series.

  Parameters:
    `start` - the index of the first time period to copy.
    `end` - the index of the last time period to copy.
  Returns:
    A series containing a copy of this times series from start until end.
  Throws:
    `java.lang.CloneNotSupportedException` - if there is a cloning problem.

### createCopy

    public TimeSeries createCopy(RegularTimePeriod start,
                                 RegularTimePeriod end)
                          throws java.lang.CloneNotSupportedException

  Creates a new timeseries by copying a subset of the data in this time series.

  Parameters:
    `start` - the first time period to copy (`null` not permitted).
    `end` - the last time period to copy (`null` not permitted).
  Returns:
    A time series containing a copy of this time series from start until end.
  Throws:
    `java.lang.CloneNotSupportedException` - if there is a cloning problem.

### equals

    public boolean equals(java.lang.Object object)

  Tests the series for equality with an arbitrary object.

  Overrides:
    `equals` in class `Series`
  Parameters:
    `object` - the object to test against (`null` permitted).
  Returns:
    A boolean.

### hashCode

    public int hashCode()

  Returns a hash code value for the object.

  Overrides:
    `hashCode` in class `Series`
  Returns:
    The hashcode