Class XYSeries

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

    public class XYSeries
    extends Series
    implements java.lang.Cloneable, java.io.Serializable
    Represents a sequence of zero or more data items in the form (x, y). By default, items in the series will be sorted into ascending order by x-value, and duplicate x-values are permitted. Both the sorting and duplicate defaults can be changed in the constructor. Y-values can be null to represent missing values.
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean allowDuplicateXValues
      A flag that controls whether or not duplicate x-values are allowed.
      private boolean autoSort
      A flag that controls whether the items are automatically sorted (by x-value ascending).
      protected java.util.List data
      Storage for the data items in the series.
      private int maximumItemCount
      The maximum number of items for the series.
      private double maxX
      The highest x-value in the series, excluding Double.NaN values.
      private double maxY
      The highest y-value in the series, excluding Double.NaN values.
      private double minX
      The lowest x-value in the series, excluding Double.NaN values.
      private double minY
      The lowest y-value in the series, excluding Double.NaN values.
      (package private) static long serialVersionUID
      For serialization.
    • Constructor Summary

      Constructors 
      Constructor Description
      XYSeries​(java.lang.Comparable key)
      Creates a new empty series.
      XYSeries​(java.lang.Comparable key, boolean autoSort)
      Constructs a new empty series, with the auto-sort flag set as requested, and duplicate values allowed.
      XYSeries​(java.lang.Comparable key, boolean autoSort, boolean allowDuplicateXValues)
      Constructs a new xy-series that contains no data.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(double x, double y)
      Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
      void add​(double x, double y, boolean notify)
      Adds a data item to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.
      void add​(double x, java.lang.Number y)
      Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
      void add​(double x, java.lang.Number y, boolean notify)
      Adds a data item to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.
      void add​(java.lang.Number x, java.lang.Number y)
      Adds a new data item to the series (in the correct position if the autoSort flag is set for the series) and sends a SeriesChangeEvent to all registered listeners.
      void add​(java.lang.Number x, java.lang.Number y, boolean notify)
      Adds new data to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.
      void add​(XYDataItem item)
      Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
      void add​(XYDataItem item, boolean notify)
      Adds a data item to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.
      XYDataItem addOrUpdate​(double x, double y)
      Adds or updates an item in the series and sends a SeriesChangeEvent to all registered listeners.
      XYDataItem addOrUpdate​(java.lang.Number x, java.lang.Number y)
      Adds or updates an item in the series and sends a SeriesChangeEvent to all registered listeners.
      XYDataItem addOrUpdate​(XYDataItem item)
      Adds or updates an item in the 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 series.
      XYSeries createCopy​(int start, int end)
      Creates a new series by copying a subset of the data in this time series.
      void delete​(int start, int end)
      Deletes a range of items from the series and sends a SeriesChangeEvent to all registered listeners.
      boolean equals​(java.lang.Object obj)
      Tests this series for equality with an arbitrary object.
      private void findBoundsByIteration()
      Finds the bounds of the x and y values for the series, by iterating through all the data items.
      boolean getAllowDuplicateXValues()
      Returns a flag that controls whether duplicate x-values are allowed.
      boolean getAutoSort()
      Returns the flag that controls whether the items in the series are automatically sorted.
      XYDataItem getDataItem​(int index)
      Return the data item with the specified index.
      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 XYDataItem objects and is unmodifiable).
      int getMaximumItemCount()
      Returns the maximum number of items that will be retained in the series.
      double getMaxX()
      Returns the largest x-value in the series, ignoring any Double.NaN values.
      double getMaxY()
      Returns the largest y-value in the series, ignoring any Double.NaN values.
      double getMinX()
      Returns the smallest x-value in the series, ignoring any Double.NaN values.
      double getMinY()
      Returns the smallest y-value in the series, ignoring any null and Double.NaN values.
      (package private) XYDataItem getRawDataItem​(int index)
      Return the data item with the specified index.
      java.lang.Number getX​(int index)
      Returns the x-value at the specified index.
      java.lang.Number getY​(int index)
      Returns the y-value at the specified index.
      int hashCode()
      Returns a hash code.
      int indexOf​(java.lang.Number x)
      Returns the index of the item with the specified x-value, or a negative index if the series does not contain an item with that x-value.
      private double maxIgnoreNaN​(double a, double b)
      A function to find the maximum of two values, but ignoring any Double.NaN values.
      private double minIgnoreNaN​(double a, double b)
      A function to find the minimum of two values, but ignoring any Double.NaN values.
      XYDataItem remove​(int index)
      Removes the item at the specified index and sends a SeriesChangeEvent to all registered listeners.
      XYDataItem remove​(java.lang.Number x)
      Removes an item with the specified x-value and sends a SeriesChangeEvent to all registered listeners.
      void setMaximumItemCount​(int maximum)
      Sets the maximum number of items that will be retained in the series.
      double[][] toArray()
      Returns a new array containing the x and y values from this series.
      void update​(java.lang.Number x, java.lang.Number y)
      Updates an item in the series.
      private void updateBoundsForAddedItem​(XYDataItem item)
      Updates the cached values for the minimum and maximum data values.
      private void updateBoundsForRemovedItem​(XYDataItem item)
      Updates the cached values for the minimum and maximum data values on the basis that the specified item has just been removed.
      void updateByIndex​(int index, java.lang.Number y)
      Updates the value of an item in the series and sends a SeriesChangeEvent to all registered listeners.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • serialVersionUID

        static final long serialVersionUID
        For serialization.
        See Also:
        Constant Field Values
      • data

        protected java.util.List data
        Storage for the data items in the series.
      • maximumItemCount

        private int maximumItemCount
        The maximum number of items for the series.
      • autoSort

        private boolean autoSort
        A flag that controls whether the items are automatically sorted (by x-value ascending).
      • allowDuplicateXValues

        private boolean allowDuplicateXValues
        A flag that controls whether or not duplicate x-values are allowed.
      • minX

        private double minX
        The lowest x-value in the series, excluding Double.NaN values.
      • maxX

        private double maxX
        The highest x-value in the series, excluding Double.NaN values.
      • minY

        private double minY
        The lowest y-value in the series, excluding Double.NaN values.
      • maxY

        private double maxY
        The highest y-value in the series, excluding Double.NaN values.
    • Constructor Detail

      • XYSeries

        public XYSeries​(java.lang.Comparable key)
        Creates a new empty series. By default, items added to the series will be sorted into ascending order by x-value, and duplicate x-values will be allowed (these defaults can be modified with another constructor).
        Parameters:
        key - the series key (null not permitted).
      • XYSeries

        public XYSeries​(java.lang.Comparable key,
                        boolean autoSort)
        Constructs a new empty series, with the auto-sort flag set as requested, and duplicate values allowed.
        Parameters:
        key - the series key (null not permitted).
        autoSort - a flag that controls whether or not the items in the series are sorted.
      • XYSeries

        public XYSeries​(java.lang.Comparable key,
                        boolean autoSort,
                        boolean allowDuplicateXValues)
        Constructs a new xy-series that contains no data. You can specify whether or not duplicate x-values are allowed for the series.
        Parameters:
        key - the series key (null not permitted).
        autoSort - a flag that controls whether or not the items in the series are sorted.
        allowDuplicateXValues - a flag that controls whether duplicate x-values are allowed.
    • Method Detail

      • getMinX

        public double getMinX()
        Returns the smallest x-value in the series, ignoring any Double.NaN values. This method returns Double.NaN if there is no smallest x-value (for example, when the series is empty).
        Returns:
        The smallest x-value.
        See Also:
        getMaxX()
      • getMaxX

        public double getMaxX()
        Returns the largest x-value in the series, ignoring any Double.NaN values. This method returns Double.NaN if there is no largest x-value (for example, when the series is empty).
        Returns:
        The largest x-value.
        See Also:
        getMinX()
      • getMinY

        public double getMinY()
        Returns the smallest y-value in the series, ignoring any null and Double.NaN values. This method returns Double.NaN if there is no smallest y-value (for example, when the series is empty).
        Returns:
        The smallest y-value.
        See Also:
        getMaxY()
      • getMaxY

        public double getMaxY()
        Returns the largest y-value in the series, ignoring any Double.NaN values. This method returns Double.NaN if there is no largest y-value (for example, when the series is empty).
        Returns:
        The largest y-value.
        See Also:
        getMinY()
      • updateBoundsForAddedItem

        private void updateBoundsForAddedItem​(XYDataItem item)
        Updates the cached values for the minimum and maximum data values.
        Parameters:
        item - the item added (null not permitted).
      • updateBoundsForRemovedItem

        private void updateBoundsForRemovedItem​(XYDataItem item)
        Updates the cached values for the minimum and maximum data values on the basis that the specified item has just been removed.
        Parameters:
        item - the item added (null not permitted).
      • findBoundsByIteration

        private void findBoundsByIteration()
        Finds the bounds of the x and y values for the series, by iterating through all the data items.
      • getAutoSort

        public boolean getAutoSort()
        Returns the flag that controls whether the items in the series are automatically sorted. There is no setter for this flag, it must be defined in the series constructor.
        Returns:
        A boolean.
      • getAllowDuplicateXValues

        public boolean getAllowDuplicateXValues()
        Returns a flag that controls whether duplicate x-values are allowed. This flag can only be set in the constructor.
        Returns:
        A boolean.
      • getItemCount

        public int getItemCount()
        Returns the number of items in the series.
        Specified by:
        getItemCount in class Series
        Returns:
        The item count.
        See Also:
        getItems()
      • getItems

        public java.util.List getItems()
        Returns the list of data items for the series (the list contains XYDataItem 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.

        Typically this value is set before the series is populated with data, but if it is applied later, it may cause some items to be removed from the series (in which case a SeriesChangeEvent will be sent to all registered listeners).

        Parameters:
        maximum - the maximum number of items for the series.
      • add

        public void add​(XYDataItem item)
        Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        item - the (x, y) item (null not permitted).
      • add

        public void add​(double x,
                        double y)
        Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        x - the x value.
        y - the y value.
      • add

        public void add​(double x,
                        double y,
                        boolean notify)
        Adds a data item to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        x - the x value.
        y - the y value.
        notify - a flag that controls whether or not a SeriesChangeEvent is sent to all registered listeners.
      • add

        public void add​(double x,
                        java.lang.Number y)
        Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners. The unusual pairing of parameter types is to make it easier to add null y-values.
        Parameters:
        x - the x value.
        y - the y value (null permitted).
      • add

        public void add​(double x,
                        java.lang.Number y,
                        boolean notify)
        Adds a data item to the series and, if requested, sends a SeriesChangeEvent to all registered listeners. The unusual pairing of parameter types is to make it easier to add null y-values.
        Parameters:
        x - the x value.
        y - the y value (null permitted).
        notify - a flag that controls whether or not a SeriesChangeEvent is sent to all registered listeners.
      • add

        public void add​(java.lang.Number x,
                        java.lang.Number y)
        Adds a new data item to the series (in the correct position if the autoSort flag is set for the series) and sends a SeriesChangeEvent to all registered listeners.

        Throws an exception if the x-value is a duplicate AND the allowDuplicateXValues flag is false.

        Parameters:
        x - the x-value (null not permitted).
        y - the y-value (null permitted).
        Throws:
        SeriesException - if the x-value is a duplicate and the allowDuplicateXValues flag is not set for this series.
      • add

        public void add​(java.lang.Number x,
                        java.lang.Number y,
                        boolean notify)
        Adds new data to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.

        Throws an exception if the x-value is a duplicate AND the allowDuplicateXValues flag is false.

        Parameters:
        x - the x-value (null not permitted).
        y - the y-value (null permitted).
        notify - a flag the controls whether or not a SeriesChangeEvent is sent to all registered listeners.
      • add

        public void add​(XYDataItem item,
                        boolean notify)
        Adds a data item to the series and, if requested, sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        item - the (x, y) item (null not permitted).
        notify - a flag that controls whether or not a SeriesChangeEvent is sent to all registered listeners.
      • delete

        public void delete​(int start,
                           int end)
        Deletes a range of items from the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        start - the start index (zero-based).
        end - the end index (zero-based).
      • remove

        public XYDataItem remove​(int index)
        Removes the item at the specified index and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        index - the index.
        Returns:
        The item removed.
      • remove

        public XYDataItem remove​(java.lang.Number x)
        Removes an item with the specified x-value and sends a SeriesChangeEvent to all registered listeners. Note that when a series permits multiple items with the same x-value, this method could remove any one of the items with that x-value.
        Parameters:
        x - the x-value.
        Returns:
        The item removed.
      • clear

        public void clear()
        Removes all data items from the series and sends a SeriesChangeEvent to all registered listeners.
      • getDataItem

        public XYDataItem getDataItem​(int index)
        Return the data item with the specified index.
        Parameters:
        index - the index.
        Returns:
        The data item with the specified index.
      • getRawDataItem

        XYDataItem getRawDataItem​(int index)
        Return the data item with the specified index.
        Parameters:
        index - the index.
        Returns:
        The data item with the specified index.
      • getX

        public java.lang.Number getX​(int index)
        Returns the x-value at the specified index.
        Parameters:
        index - the index (zero-based).
        Returns:
        The x-value (never null).
      • getY

        public java.lang.Number getY​(int index)
        Returns the y-value at the specified index.
        Parameters:
        index - the index (zero-based).
        Returns:
        The y-value (possibly null).
      • minIgnoreNaN

        private double minIgnoreNaN​(double a,
                                    double b)
        A function to find the minimum of two values, but ignoring any Double.NaN values.
        Parameters:
        a - the first value.
        b - the second value.
        Returns:
        The minimum of the two values.
      • maxIgnoreNaN

        private double maxIgnoreNaN​(double a,
                                    double b)
        A function to find the maximum of two values, but ignoring any Double.NaN values.
        Parameters:
        a - the first value.
        b - the second value.
        Returns:
        The maximum of the two values.
      • updateByIndex

        public void updateByIndex​(int index,
                                  java.lang.Number y)
        Updates the value of an item in the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        index - the item (zero based index).
        y - the new value (null permitted).
      • update

        public void update​(java.lang.Number x,
                           java.lang.Number y)
        Updates an item in the series.
        Parameters:
        x - the x-value (null not permitted).
        y - the y-value (null permitted).
        Throws:
        SeriesException - if there is no existing item with the specified x-value.
      • addOrUpdate

        public XYDataItem addOrUpdate​(double x,
                                      double y)
        Adds or updates an item in the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        x - the x-value.
        y - the y-value.
        Returns:
        The item that was overwritten, if any.
      • addOrUpdate

        public XYDataItem addOrUpdate​(java.lang.Number x,
                                      java.lang.Number y)
        Adds or updates an item in the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        x - the x-value (null not permitted).
        y - the y-value (null permitted).
        Returns:
        A copy of the overwritten data item, or null if no item was overwritten.
      • addOrUpdate

        public XYDataItem addOrUpdate​(XYDataItem item)
        Adds or updates an item in the series and sends a SeriesChangeEvent to all registered listeners.
        Parameters:
        item - the data item (null not permitted).
        Returns:
        A copy of the overwritten data item, or null if no item was overwritten.
      • indexOf

        public int indexOf​(java.lang.Number x)
        Returns the index of the item with the specified x-value, or a negative index if the series does not contain an item with that x-value. Be aware that for an unsorted series, the index is found by iterating through all items in the series.
        Parameters:
        x - the x-value (null not permitted).
        Returns:
        The index.
      • toArray

        public double[][] toArray()
        Returns a new array containing the x and y values from this series.
        Returns:
        A new array containing the x and y values from this series.
      • clone

        public java.lang.Object clone()
                               throws java.lang.CloneNotSupportedException
        Returns a clone of the series.
        Overrides:
        clone in class Series
        Returns:
        A clone of the series.
        Throws:
        java.lang.CloneNotSupportedException - if there is a cloning problem.
      • createCopy

        public XYSeries createCopy​(int start,
                                   int end)
                            throws java.lang.CloneNotSupportedException
        Creates a new series by copying a subset of the data in this time series.
        Parameters:
        start - the index of the first item to copy.
        end - the index of the last item to copy.
        Returns:
        A series containing a copy of this series from start until end.
        Throws:
        java.lang.CloneNotSupportedException - if there is a cloning problem.
      • equals

        public boolean equals​(java.lang.Object obj)
        Tests this series for equality with an arbitrary object.
        Overrides:
        equals in class Series
        Parameters:
        obj - the object to test against for equality (null permitted).
        Returns:
        A boolean.
      • hashCode

        public int hashCode()
        Returns a hash code.
        Overrides:
        hashCode in class Series
        Returns:
        A hash code.