Interface for accessing data types as though they were a read-only const array of doubles.
More...
A DataSeries is an interface for accessing some underlying data as though it was a const array of doubles. More precisely, the array can be assumed to support random access through operator[](int). Normally, this implies constant time lookup for any argument passed to operator[](int), but here we relax the requirement such that lookup is O(d) where d is the absolute difference between the parameter passed to the current and the previous call. This is important, because the typical usage of a DataSeries is to iterate through it from beginning to end, or over some sequential sub-range. In such cases, the lookup then effectively reduces to constant time and the performance characteristics are similar to a regular array. This relaxation of the complexity requirements allows subclasses to be constructed over containers that support bi-directional iterators but not true random access iterators, such as a linked list. Even more powerfully, a DataSeries subclass can then be a proxy for some arbitrary data that is not even stored as a sequential array, but can be made to appear so.
It should be noted that subclasses are not expected to be thread-safe. This is so that subclasses are free to employ internal caching mechanisms to improve the performance of operator[]() if they represent data that supports bi-directional iterators rather than random access iterators (eg a linked list), as described above.
Algorithm implementers should ensure they consider the relaxed complexity requirements and anticipate that DataSeries subclasses will be optimized for sequential access. Calls to operator[]() should aim to differ by no more than one index from a previous call if at all possible. Perhaps the best approach is to avoid directly calling operator[]() altogether and instead use iterator-based access with only increment or decrement operations on the iterators.
Note that as a special case, a data series can be considered infinite. An infinite data series returns zero from size() but false from empty(). The isInfinite() function is provided as a convenience for testing this and to make client code clearer. For an infinite data series, any valid integer may be passed to operator[](int) and a meaningful return value can be expected. This has implications for iterators though, since the series technically has no beginning or end. So that iterators can still be used by algorithms operating on a subrange within an infinite series, some of the requirements on iterators are modified from the standard requirements of a random access iterator when isInfinite() returns true:
- The const_iterator returned from begin() must always be dereferencable and must correspond to passing a value of zero to operator[](int).
- Calling std::advance() on any const_iterator returned from begin() will return a const_iterator that is dereferencable, regardless of the distance argument passed to std::advance().
- The result of end() will always be the same as the result of begin(), so the range [begin(), end()) is always technically empty for an infinite series. Any algorithm that wants to operate on a range within an infinite series must construct the two iterators based on begin() and std::advance() only (ie end() must not be used).
Finally, although DataSeries is derived from Clonable, this should be understood to mean that the subclass is cloned but not necessarily the data it represents (and indeed will usually not mean the underlying data is cloned). The DataSeries class is meant to act as an adaptor to some other underlying data that is managed by something else. Clients of the DataSeries class should be able to call clone() and expect the call to be relatively cheap.
- See also
- NullDataSeries, SequenceDataSeries, DataSeriesAdaptor
Public Member Functions inherited from Clonable