Package com.amalgamasimulation.utils.time

Class TimeSeries

java.lang.Object
com.amalgamasimulation.utils.time.TimeSeries
Direct Known Subclasses:
BoundedTimeSeries, CompoundTimeSeries, RelativeTimeSeries, RepeatingTimeSeries, SingleTimeSeries
public abstract class TimeSeries extends Object
Time series is a finite or potentially infinite sequence of instants of calendar time.
  • Example of single instant time series is: "At 9:30am on 2nd of January 2024"
  • Example of multiple instant time series is "Every Friday at 6pm", or "Every day at midday"
When a time series is supplied with a Timeable, which provides translation from calendar dates to number based values of instants, a time series becomes capable of returning instants as double values.
Author:
Andrey Malykhanov

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Timeable
    timeable
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    TimeSeries(Timeable timeable)
    Creates a new instance of time series with the specified Timeable that provides translation from calendar dates to number based values of instants.

  • Method Summary

    Modifier and Type
    Method
    Description
    static EveryMonthTimeSeries
    everyMonth(LocalTime instantTime, int dayOfMonthIndex, Timeable timeable)
    Returns a time series containing instants formed according to the rule: "At the specified time of the specified day of month every month".
    static EveryMonthLastDayTimeSeries
    everyMonthLastDay(LocalTime instantTime, Timeable timeable)
    Returns a time series containing instants formed according to the rule: "At the specified time on the last day of every month".
    static EveryNDaysTimeSeries
    everyNDaysTimeSeries(LocalTime instantTime, int nDays, Timeable timeable)
    Returns a time series containing instants formed according to the rule: "At the specified time of day every n days".
    static EveryWeekTimeSeries
    everyWeekTimeSeries(LocalTime instantTime, DayOfWeek dayOfWeek, Timeable timeable)
    Returns a time series containing instants formed according to the rule: "Every specified weekday at the specified time of day".
    List<Double>
    getInstantsTimes(double beginTime, double endTime)
    Returns an unmodifiable list containing all times of instants of this time series between the specified times.
    abstract List<Double>
    getInstantsTimes(double beginTime, double endTime, boolean beginTimeInclusive, boolean endTimeInclusive)
    Returns an unmodifiable list containing all times of instants of this time series between the specified times.
    double
    getNextInstantTime(double atOrAfterTime)
    Returns the time of the smallest instant of this time series that is equal to or greater than the specified time, or Double.POSITIVE_INFINITY if there are no such instants in this time series.
    abstract double
    getNextInstantTime(double time, boolean timeInclusive)
    Returns the time of the smallest instant of this time series after the specified time, or Double.POSITIVE_INFINITY if there are no such instants in this time series.
    abstract double
    getPreviousInstantTime(double beforeTime)
    Returns the time of the biggest instant of this time series that is strictly less than the the specified time, or Double.NEGATIVE_INFINITY if there is no such instant.
    static CompoundTimeSeries
    of(TimeSeries... timeSeriesInstances)
    Returns a compound time series that contains the union of all specified time series instances.
    static BoundedTimeSeries
    of(TimeSeries timeSeriesInstance, double beginTime, double endTime)
    Returns a new instance of BoundedTimeSeries that bounds an instance of the specified time series on the left and right along the time axis.
    static BoundedTimeSeries
    of(TimeSeries timeSeriesInstance, LocalDateTime beginDate, LocalDateTime endDate)
    Returns a new instance of TimeSeries that bounds an instance of the specified time series on the left and right along the time axis.
    static RelativeTimeSeries
    relativeTimeSeries(TimeSeries baseTimeSeries, double offset, ChronoUnit offsetChronoUnit)
    Returns a time series that is obtained from the specified base time series by shifting all its instants by the specified amount of the specified time units.
    static SingleTimeSeries
    singleTimeSeries(double instantTime)
    Returns a time series containing a single instant at the specified number based instant value.
    static SingleTimeSeries
    singleTimeSeries(LocalDateTime instantDateTime, Timeable timeable)
    Returns a time series containing a single instant at the specified calendar date and time.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • timeable

      protected Timeable timeable

  • Constructor Details

    • TimeSeries

      protected TimeSeries(Timeable timeable)
      Creates a new instance of time series with the specified Timeable that provides translation from calendar dates to number based values of instants.
      Parameters:
      timeable - specified Timeable instance

  • Method Details

    • getNextInstantTime

      public double getNextInstantTime(double atOrAfterTime)
      Returns the time of the smallest instant of this time series that is equal to or greater than the specified time, or Double.POSITIVE_INFINITY if there are no such instants in this time series.
      Parameters:
      atOrAfterTime - specified time, inclusively
      Returns:
      time of the smallest instant equal to or greater than the specified time, or Double.POSITIVE_INFINITY

    • getInstantsTimes

      public List<Double> getInstantsTimes(double beginTime, double endTime)
      Returns an unmodifiable list containing all times of instants of this time series between the specified times. If there are no such instants, an empty list is returned.
      Parameters:
      beginTime - smallest time of instants being returned, inclusively
      endTime - biggest time of instants being returned, exclusively
      Returns:
      unmodifiable list containing all times of instants of this time series between the specified times

    • getPreviousInstantTime

      public abstract double getPreviousInstantTime(double beforeTime)
      Returns the time of the biggest instant of this time series that is strictly less than the the specified time, or Double.NEGATIVE_INFINITY if there is no such instant.
      Parameters:
      beforeTime - specified time
      Returns:
      time of the biggest instant of this time series that is strictly less than the the specified time, or Double.NEGATIVE_INFINITY

    • getNextInstantTime

      public abstract double getNextInstantTime(double time, boolean timeInclusive)
      Returns the time of the smallest instant of this time series after the specified time, or Double.POSITIVE_INFINITY if there are no such instants in this time series. Allows to include or exclude the specified time itself.
      Parameters:
      time - specified time
      timeInclusive - whether to include or exclude the specified time
      Returns:
      time of the smallest instant of this time series after the specified time, or Double.POSITIVE_INFINITY

    • getInstantsTimes

      public abstract List<Double> getInstantsTimes(double beginTime, double endTime, boolean beginTimeInclusive, boolean endTimeInclusive)
      Returns an unmodifiable list containing all times of instants of this time series between the specified times. If there are no such instants, an empty list is returned. Allows to include or exclude the boundaries of the specified time interval.
      Parameters:
      beginTime - smallest time of instants being returned
      endTime - biggest time of instants being returned
      beginTimeInclusive - whether to include or exclude the right boundary (beginTime)
      endTimeInclusive - whether to include or exclude the left boundary (endTime)
      Returns:
      unmodifiable list containing all times of instants of this time series between the specified times

    • of

      public static CompoundTimeSeries of(TimeSeries... timeSeriesInstances)
      Returns a compound time series that contains the union of all specified time series instances.
      Parameters:
      timeSeriesInstances - specified time series instances
      Returns:
      compound time series that contains the union of all specified time series instances.

    • of

      public static BoundedTimeSeries of(TimeSeries timeSeriesInstance, double beginTime, double endTime)
      Returns a new instance of BoundedTimeSeries that bounds an instance of the specified time series on the left and right along the time axis.
      Parameters:
      timeSeriesInstance - specified time series instances
      beginTime - left time boundary
      endTime - right time boundary

    • of

      public static BoundedTimeSeries of(TimeSeries timeSeriesInstance, LocalDateTime beginDate, LocalDateTime endDate)
      Returns a new instance of TimeSeries that bounds an instance of the specified time series on the left and right along the time axis.
      Parameters:
      timeSeriesInstance - specified time series instances
      beginDate - left date time boundary
      endDate - right date time boundary

    • everyMonthLastDay

      public static EveryMonthLastDayTimeSeries everyMonthLastDay(LocalTime instantTime, Timeable timeable)
      Returns a time series containing instants formed according to the rule: "At the specified time on the last day of every month".
      Parameters:
      instantTime - specified time of day
      timeable - Timeable instance that provides translation from calendar dates to number based values of instants
      Returns:
      time series instance

    • everyMonth

      public static EveryMonthTimeSeries everyMonth(LocalTime instantTime, int dayOfMonthIndex, Timeable timeable)
      Returns a time series containing instants formed according to the rule: "At the specified time of the specified day of month every month". For day indexes greater than 28, some months will be skipped and will not produce instants of this time series.
      Parameters:
      instantTime - specified time of day
      dayOfMonthIndex - specified day of month, must be between 1 and 31, inclusively
      timeable - Timeable instance that provides translation from calendar dates to number based values of instants
      Returns:
      time series instance

    • everyNDaysTimeSeries

      public static EveryNDaysTimeSeries everyNDaysTimeSeries(LocalTime instantTime, int nDays, Timeable timeable)
      Returns a time series containing instants formed according to the rule: "At the specified time of day every n days". Time series with daily instants can be produced by specifying nDays = 1.
      Parameters:
      instantTime - specified time of day
      nDays - period in days, must be positive
      timeable - Timeable instance that provides translation from calendar dates to number based values of instants
      Returns:
      time series instance

    • everyWeekTimeSeries

      public static EveryWeekTimeSeries everyWeekTimeSeries(LocalTime instantTime, DayOfWeek dayOfWeek, Timeable timeable)
      Returns a time series containing instants formed according to the rule: "Every specified weekday at the specified time of day".
      Parameters:
      instantTime - specified time of day
      dayOfWeek - specified weekday
      timeable - Timeable instance that provides translation from calendar dates to number based values of instants
      Returns:
      time series instance

    • singleTimeSeries

      public static SingleTimeSeries singleTimeSeries(LocalDateTime instantDateTime, Timeable timeable)
      Returns a time series containing a single instant at the specified calendar date and time.
      Parameters:
      instantDateTime - specified calendar date and time
      timeable - Timeable instance that provides translation from calendar dates to number based values of instants
      Returns:
      time series instance

    • singleTimeSeries

      public static SingleTimeSeries singleTimeSeries(double instantTime)
      Returns a time series containing a single instant at the specified number based instant value.
      Parameters:
      instantTime - specified number based instant value
      Returns:
      time series instance

    • relativeTimeSeries

      public static RelativeTimeSeries relativeTimeSeries(TimeSeries baseTimeSeries, double offset, ChronoUnit offsetChronoUnit)
      Returns a time series that is obtained from the specified base time series by shifting all its instants by the specified amount of the specified time units.
      Parameters:
      baseTimeSeries - specified base time series that is being shifted
      offset - offset shift, can be positive or negative, must be finite
      offsetChronoUnit - time unit of the offset
      Returns:
      time series instance