## Interface LocalDateDoubleTimeSeries

• public interface LocalDateDoubleTimeSeries
Interface for all local date time-series types containing double values.

A time-series is similar to both a SortedMap of value keyed by date-time and a List of date-time to value pairs. As such, the date/times do not have to be evenly spread over time within the series.

The distribution of the data will influence which implementation is most appropriate.

Implementations must be immutable and thread-safe beans.

Note that Double.NaN is used internally as a sentinel value and is therefore not allowed as a value.

• ### Method Summary

All Methods
Modifier and Type Method Description
static LocalDateDoubleTimeSeriesBuilder builder()
Creates an empty builder, used to create time-series.
static java.util.stream.Collector<LocalDateDoublePoint,​LocalDateDoubleTimeSeriesBuilder,​LocalDateDoubleTimeSeries> collector()
Returns a collector that can be used to create a time-series from a stream of points.
boolean containsDate​(java.time.LocalDate date)
Checks if this time-series contains a value for the specified date.
java.util.stream.Stream<java.time.LocalDate> dates()
Returns a stream over the dates of this time-series.
static LocalDateDoubleTimeSeries empty()
Returns an empty time-series.
LocalDateDoubleTimeSeries filter​(ObjDoublePredicate<java.time.LocalDate> predicate)
Create a new time-series by filtering this one.
void forEach​(java.util.function.ObjDoubleConsumer<java.time.LocalDate> action)
Applies an action to each pair in the time series.
java.util.OptionalDouble get​(java.time.LocalDate date)
Gets the value associated with the specified date.
default java.time.LocalDate getEarliestDate()
Get the earliest date contained in this time-series.
default double getEarliestValue()
Get the value held for the earliest date contained in this time-series.
java.time.LocalDate getLatestDate()
Get the latest date contained in this time-series.
double getLatestValue()
Get the value held for the latest date contained in this time-series.
LocalDateDoubleTimeSeries headSeries​(int numPoints)
Gets part of this series as a sub-series, choosing the earliest entries.
default LocalDateDoubleTimeSeries intersection​(LocalDateDoubleTimeSeries other, java.util.function.DoubleBinaryOperator mapper)
Obtains the intersection of a pair of time series.
boolean isEmpty()
Indicates if this time-series is empty.
LocalDateDoubleTimeSeries mapDates​(java.util.function.Function<? super java.time.LocalDate,​? extends java.time.LocalDate> mapper)
Applies an operation to each date in the time series which creates a new date, returning a new time series with the new dates and the points from this time series.
LocalDateDoubleTimeSeries mapValues​(java.util.function.DoubleUnaryOperator mapper)
Applies an operation to each value in the time series.
static LocalDateDoubleTimeSeries of​(java.time.LocalDate date, double value)
Obtains a time-series containing a single date and value.
default Pair<LocalDateDoubleTimeSeries,​LocalDateDoubleTimeSeries> partition​(ObjDoublePredicate<java.time.LocalDate> predicate)
Partition the time-series into a pair of distinct series using a predicate.
default Pair<LocalDateDoubleTimeSeries,​LocalDateDoubleTimeSeries> partitionByValue​(java.util.function.DoublePredicate predicate)
Partition the time-series into a pair of distinct series using a predicate.
int size()
Return the size of this time-series.
java.util.stream.Stream<LocalDateDoublePoint> stream()
Returns a stream over the points of this time-series.
LocalDateDoubleTimeSeries subSeries​(java.time.LocalDate startInclusive, java.time.LocalDate endExclusive)
Gets part of this series as a sub-series between two dates.
LocalDateDoubleTimeSeries tailSeries​(int numPoints)
Gets part of this series as a sub-series, choosing the latest entries.
LocalDateDoubleTimeSeriesBuilder toBuilder()
Return a builder populated with the values from this series.
default LocalDateDoubleTimeSeries union​(LocalDateDoubleTimeSeries other, java.util.function.DoubleBinaryOperator mapper)
Obtains the union of a pair of time series.
java.util.stream.DoubleStream values()
Returns a stream over the values of this time-series.
• ### Method Detail

• #### empty

static LocalDateDoubleTimeSeries empty()
Returns an empty time-series. Generally a singleton instance is returned.
Returns:
an empty time-series
• #### of

static LocalDateDoubleTimeSeries of​(java.time.LocalDate date,
double value)
Obtains a time-series containing a single date and value.
Parameters:
date - the singleton date
value - the singleton value
Returns:
the time-series
• #### builder

static LocalDateDoubleTimeSeriesBuilder builder()
Creates an empty builder, used to create time-series.

The builder has methods to create and modify a time-series.

Returns:
the time-series builder
• #### collector

static java.util.stream.Collector<LocalDateDoublePoint,​LocalDateDoubleTimeSeriesBuilder,​LocalDateDoubleTimeSeries> collector()
Returns a collector that can be used to create a time-series from a stream of points.
Returns:
the time-series collector
• #### size

int size()
Return the size of this time-series.
Returns:
the size of the time-series
• #### isEmpty

boolean isEmpty()
Indicates if this time-series is empty.
Returns:
true if the time-series contains no entries
• #### containsDate

boolean containsDate​(java.time.LocalDate date)
Checks if this time-series contains a value for the specified date.
Parameters:
date - the date to check for
Returns:
true if there is a value associated with the date
• #### get

java.util.OptionalDouble get​(java.time.LocalDate date)
Gets the value associated with the specified date.

The result is an OptionalDouble which avoids the need to handle null or exceptions. Use isPresent() to check whether the value is present. Use orElse(double) to default a missing value.

Parameters:
date - the date to get the value for
Returns:
the value associated with the date, optional empty if the date is not present
• #### getEarliestDate

default java.time.LocalDate getEarliestDate()
Get the earliest date contained in this time-series.

If the time-series is empty then NoSuchElementException will be thrown.

Returns:
the earliest date contained in this time-series
Throws:
java.util.NoSuchElementException - if the time-series is empty
• #### getEarliestValue

default double getEarliestValue()
Get the value held for the earliest date contained in this time-series.

If the time-series is empty then NoSuchElementException will be thrown.

Returns:
the value held for the earliest date contained in this time-series
Throws:
java.util.NoSuchElementException - if the time-series is empty
• #### getLatestDate

java.time.LocalDate getLatestDate()
Get the latest date contained in this time-series.

If the time-series is empty then NoSuchElementException will be thrown.

Returns:
the latest date contained in this time-series
Throws:
java.util.NoSuchElementException - if the time-series is empty
• #### getLatestValue

double getLatestValue()
Get the value held for the latest date contained in this time-series.

If the time-series is empty then NoSuchElementException will be thrown.

Returns:
the value held for the latest date contained in this time-series
Throws:
java.util.NoSuchElementException - if the time-series is empty
• #### subSeries

LocalDateDoubleTimeSeries subSeries​(java.time.LocalDate startInclusive,
java.time.LocalDate endExclusive)
Gets part of this series as a sub-series between two dates.

The date-times do not have to match exactly. The sub-series contains all entries between the two dates using a half-open interval. The start date is included, the end date is excluded. The dates may be before or after the end of the time-series.

To obtain the series before a specific date, used LocalDate.MIN as the first argument. To obtain the series from a specific date, used LocalDate.MAX as the second argument.

Parameters:
startInclusive - the start date, inclusive
endExclusive - the end date, exclusive
Returns:
the sub-series between the dates
Throws:
java.lang.IllegalArgumentException - if the end is before the start

LocalDateDoubleTimeSeries headSeries​(int numPoints)
Gets part of this series as a sub-series, choosing the earliest entries.

The sub-series contains the earliest part of the series up to the specified number of points. If the series contains less points than the number requested, the whole time-series is returned.

Parameters:
numPoints - the number of items to select, zero or greater
Returns:
the sub-series of the requested size starting with the earliest entry
Throws:
java.lang.IllegalArgumentException - if the number of items is less than zero
• #### tailSeries

LocalDateDoubleTimeSeries tailSeries​(int numPoints)
Gets part of this series as a sub-series, choosing the latest entries.

The sub-series contains the latest part of the series up to the specified number of points. If the series contains less points than the number requested, the whole time-series is returned.

Parameters:
numPoints - the number of items to select, zero or greater
Returns:
the sub-series of the requested size ending with the latest entry
Throws:
java.lang.IllegalArgumentException - if the number of items is less than zero
• #### stream

java.util.stream.Stream<LocalDateDoublePoint> stream()
Returns a stream over the points of this time-series.

Returns:
a stream over the points of this time-series
• #### dates

java.util.stream.Stream<java.time.LocalDate> dates()
Returns a stream over the dates of this time-series.

This is most useful to summarize the dates in the stream, such as calculating the maximum or minimum date, or searching for a specific value.

Returns:
a stream over the dates of this time-series
• #### values

java.util.stream.DoubleStream values()
Returns a stream over the values of this time-series.

This is most useful to summarize the values in the stream, such as calculating the maximum, minimum or average value, or searching for a specific value.

Returns:
a stream over the values of this time-series
• #### forEach

void forEach​(java.util.function.ObjDoubleConsumer<java.time.LocalDate> action)
Applies an action to each pair in the time series.

This is generally used to apply a mathematical operation to the values. For example, the operator could multiply each value by a constant, or take the inverse.

   base.forEach((date, value) -> System.out.println(date + "=" + value));

Parameters:
action - the action to be applied to each pair
• #### mapDates

LocalDateDoubleTimeSeries mapDates​(java.util.function.Function<? super java.time.LocalDate,​? extends java.time.LocalDate> mapper)
Applies an operation to each date in the time series which creates a new date, returning a new time series with the new dates and the points from this time series.

This operation creates a new time series with the same data but the dates moved.

The operation must not change the dates in a way that reorders them. The mapped dates must be in ascending order or an exception is thrown.

   updatedSeries = timeSeries.mapDates(date -> date.plusYears(1));

Parameters:
mapper - the operation applied to each date in the time series
Returns:
a copy of this time series with new dates
• #### mapValues

LocalDateDoubleTimeSeries mapValues​(java.util.function.DoubleUnaryOperator mapper)
Applies an operation to each value in the time series.

This is generally used to apply a mathematical operation to the values. For example, the operator could multiply each value by a constant, or take the inverse.

   multiplied = base.mapValues(value -> value * 3);

Parameters:
mapper - the operator to be applied to the values
Returns:
a copy of this series with the mapping applied to the original values
• #### filter

LocalDateDoubleTimeSeries filter​(ObjDoublePredicate<java.time.LocalDate> predicate)
Create a new time-series by filtering this one.

The time-series can be filtered by both date and value. Note that if filtering by date range is required, it is likely to be more efficient to use subSeries(LocalDate, LocalDate) as that avoids traversal of the whole series.

Parameters:
predicate - the predicate to use to the filter the elements of the series
Returns:
a filtered version of the series
• #### intersection

default LocalDateDoubleTimeSeries intersection​(LocalDateDoubleTimeSeries other,
java.util.function.DoubleBinaryOperator mapper)
Obtains the intersection of a pair of time series.

This returns a time-series with the intersection of the dates of the two inputs. The operator is invoked to combine the values.

Parameters:
other - the time-series to combine with
mapper - the function to be used to combine the values
Returns:
a new time-series containing the dates in common between the input series with their values combined together using the function
• #### union

default LocalDateDoubleTimeSeries union​(LocalDateDoubleTimeSeries other,
java.util.function.DoubleBinaryOperator mapper)
Obtains the union of a pair of time series.

This returns a time-series with the union of the dates of the two inputs. When the same date occurs in both time-series, the operator is invoked to combine the values.

Parameters:
other - the time-series to combine with
mapper - the function to be used to combine the values
Returns:
a new time-series containing the dates in common between the input series with their values combined together using the function
• #### partition

default Pair<LocalDateDoubleTimeSeries,​LocalDateDoubleTimeSeries> partition​(ObjDoublePredicate<java.time.LocalDate> predicate)
Partition the time-series into a pair of distinct series using a predicate.

Points in the time-series which match the predicate will be put into the first series, whilst those points which do not match will be put into the second.

Parameters:
predicate - predicate used to test the points in the time-series
Returns:
a Pair containing two time-series. The first is a series made of all the points in this series which match the predicate. The second is a series made of the points which do not match.
• #### partitionByValue

default Pair<LocalDateDoubleTimeSeries,​LocalDateDoubleTimeSeries> partitionByValue​(java.util.function.DoublePredicate predicate)
Partition the time-series into a pair of distinct series using a predicate.

Points in the time-series whose values match the predicate will be put into the first series, whilst those points whose values do not match will be put into the second.

Parameters:
predicate - predicate used to test the points in the time-series
Returns:
a Pair containing two time-series. The first is a series made of all the points in this series which match the predicate. The second is a series made of the points which do not match.
• #### toBuilder

LocalDateDoubleTimeSeriesBuilder toBuilder()
Return a builder populated with the values from this series.

This can be used to mutate the time-series.

Returns:
a builder containing the point from this time-series