Package com.opengamma.strata.basics.date

Interface DateSequence

  • All Superinterfaces:
    Named
    public interface DateSequence
extends Named
    A series of dates identified by name.

    This interface encapsulates a sequence of dates as used in standard financial instruments. The most common are the quarterly IMM dates, which are on the third Wednesday of March, June, September and December.

    The most common implementations are provided in DateSequences.

    Note that the dates produced by the sequence may not be business days. The application of a holiday calendar is typically the responsibility of the caller.

    All implementations of this interface must be immutable and thread-safe.

    • Method Detail

      • of

        static DateSequence of​(String uniqueName)
        Obtains an instance from the specified unique name.
        Parameters:
        uniqueName - the unique name
        Returns:
        the date sequence
        Throws:
        IllegalArgumentException - if the name is not known

      • extendedEnum

        static ExtendedEnum<DateSequence> extendedEnum()
        Gets the extended enum helper.

        This helper allows instances of the sequence to be looked up. It also provides the complete set of available instances.

        Returns:
        the extended enum helper

      • baseSequence

        default DateSequence baseSequence()
        Returns the simpler "base" sequence underlying this one.

        Many date sequences have two interlinked sequences. One is considered to be the base sequence, the other is considered to be the full sequence.

        For example, the "base sequence" of a future is often March, June, September and December. But additionally, the nearest two "serial" months are also listed. Together these make the "full sequence".

        If this instance represents the "full sequence", this method returns the "base sequence". If this instance represents the "base sequence", or there is no "base sequence", this method returns this.

        Returns:
        the base sequence

      • next

        default LocalDate next​(LocalDate date)
        Finds the next date in the sequence, always returning a date later than the input date.

        Given an input date, this method returns the next date after it from the sequence.

        Parameters:
        date - the input date
        Returns:
        the next sequence date after the input date
        Throws:
        IllegalArgumentException - if there are no more sequence dates

      • nextOrSame

        LocalDate nextOrSame​(LocalDate date)
        Finds the next date in the sequence, returning the input date if it is a date in the sequence.

        Given an input date, this method returns a date from the sequence. If the input date is in the sequence, it is returned. Otherwise, the next date in the sequence after the input date is returned.

        Parameters:
        date - the input date
        Returns:
        the input date if it is a sequence date, otherwise the next sequence date
        Throws:
        IllegalArgumentException - if there are no more sequence dates

      • nth

        default LocalDate nth​(LocalDate date,
                      int sequenceNumber)
        Finds the nth date in the sequence after the input date, always returning a date later than the input date.

        Given an input date, this method returns a date from the sequence. If the sequence number is 1, then the first date in the sequence after the input date is returned.

        If the sequence number is 2 or larger, then the date referred to by sequence number 1 is calculated, and the nth matching sequence date after that date returned.

        Parameters:
        date - the input date
        sequenceNumber - the 1-based index of the date to find
        Returns:
        the nth sequence date after the input date
        Throws:
        IllegalArgumentException - if the sequence number is zero or negative or if there are no more sequence dates

      • nthOrSame

        default LocalDate nthOrSame​(LocalDate date,
                            int sequenceNumber)
        Finds the nth date in the sequence on or after the input date, returning the input date if it is a date in the sequence.

        Given an input date, this method returns a date from the sequence. If the sequence number is 1, then either the input date or the first date in the sequence after the input date is returned.

        If the sequence number is 2 or larger, then the date referred to by sequence number 1 is calculated, and the nth matching sequence date after that date returned.

        Parameters:
        date - the input date
        sequenceNumber - the 1-based index of the date to find
        Returns:
        the nth sequence date on or after the input date
        Throws:
        IllegalArgumentException - if the sequence number is zero or negative or if there are no more sequence dates

      • dateMatching

        LocalDate dateMatching​(YearMonth yearMonth)
        Finds the date in the sequence that corresponds to the specified year-month.

        Given an input month, this method returns the date from the sequence that is associated with the year-month. In most cases, the returned date will be in the same month as the input month, but this is not guaranteed.

        Parameters:
        yearMonth - the input year-month
        Returns:
        the next sequence date after the input date
        Throws:
        IllegalArgumentException - if there are no more sequence dates

      • selectDate

        default LocalDate selectDate​(LocalDate inputDate,
                             SequenceDate sequenceDate)
        Selects a date from the sequence.

        Given an input date, this uses the SequenceDate to select a single matching date from the sequence. If the SequenceDate specifies a year-month, the match starts from the first date of the specified month. Otherwise, the match starts from the day after the input date.

        Parameters:
        inputDate - the input date
        sequenceDate - the instructions specifying which date to select
        Returns:
        the next sequence date after the input date
        Throws:
        IllegalArgumentException - if there are no more sequence dates

      • selectDateOrSame

        default LocalDate selectDateOrSame​(LocalDate inputDate,
                                   SequenceDate sequenceDate)
        Selects a date from the sequence.

        Given an input date, this uses the SequenceDate to select a single matching date from the sequence. If the SequenceDate specifies a year-month, the match starts from the first date of the specified month. Otherwise, the match starts from the input date.

        Parameters:
        inputDate - the input date
        sequenceDate - the instructions specifying which date to select
        Returns:
        the next sequence date after the input date
        Throws:
        IllegalArgumentException - if there are no more sequence dates

      • getName

        String getName()
        Gets the name that uniquely identifies this sequence.

        This name is used in serialization and can be parsed using of(String).

        Specified by:
        getName in interface Named
        Returns:
        the unique name