Recurrences

Time spans may be expressed in many different units. The DateTimeUnit enumeration type specifies the available units:

Some units have a constant value. Others are based on the length of a month, which varies. Any time span can be expressed as the sum of a constant value and a number of months.

A recurrence pattern consists of two parts: a time span between occurrences and an offset from a larger time span. A recurrence does not have a start or end date. Start and end dates are specified when a concrete sequence of instances is generated.

Recurrences are immutable, and the Recurrence class does not have any constructors. Instead, a combination of several built-in recurrences and methods that derive new recurrences from existing ones are used. The predefined occurrences are defined as read-only fields of the Recurrence class:

A number of fields define weekly recurrences on a specific day of the week. These are Mondays, Tuesdays, and so on.

In addition, the Every method lets you define a recurrence of arbitrary length of arbitrary units. This method has two overloads. The first has two arguments: the first argument is the number of units and the second specifies the unit. The second overload has only one argument, the unit, and takes the number of units to be 1. The code below shows some examples of simple recurrences:

var everyDay = Recurrence.Daily;
var every5Minutes = Recurrence.Every(5.0, DateTimeUnit.Minute);

Dim everyDay = Recurrence.Daily
Dim every5Minutes = Recurrence.Every(5.0, DateTimeUnit.Minute)

let everyDay = Recurrence.Daily
let every5Minutes = Recurrence.Every(5.0, DateTimeUnit.Minute)

Once you have a basic recurrence object, several instance methods may be called to create more complex recurrences. The At(Int32, Int32, Double) lets you specify a time of day in hours, minutes and seconds. (Minutes and seconds are optional.)

var at915am = Recurrence.Daily.At(9, 15);
var wednesdaysAt430pm = Recurrence.Wednesdays.At(16, 30);

Dim at915am = Recurrence.Daily.At(9, 15)
Dim wednesdaysAt430pm = Recurrence.Wednesdays.At(16, 30)

let at915am = Recurrence.Daily.At(9, 15)
let wednesdaysAt430pm = Recurrence.Wednesdays.At(16, 30)

For monthly occurrences, the Day(Int32, Boolean) method returns a recurrence on the specified day of the month. An optional second argument specifies whether the day should be counted from the end. It is also possible to specify a recurrence on a specific day of the week each month. There is one method for each day of the week. Each method takes one or two arguments. The first is the week number, and the second is whether weeks are counted from the end.

var eightOfTheMonth = Recurrence.Monthly.Day(8);
var lastDayOfTheMonth = Recurrence.Monthly.Day(1, fromEnd: true);
var thirdFriday = Recurrence.Monthly.Friday(3);
var lastThursday = Recurrence.Monthly.Thursday(1, fromEnd: true);

Dim eightOfTheMonth = Recurrence.Monthly.Day(8)
Dim lastDayOfTheMonth = Recurrence.Monthly.Day(1, fromEnd:=True)
Dim thirdFriday = Recurrence.Monthly.Friday(3)
Dim lastThursday = Recurrence.Monthly.Thursday(1, fromEnd:=True)

let eightOfTheMonth = Recurrence.Monthly.Day(8)
let lastDayOfTheMonth = Recurrence.Monthly.Day(1, fromEnd=true)
let thirdFriday = Recurrence.Monthly.Friday(3)
let lastThursday = Recurrence.Monthly.Thursday(1, fromEnd=true)

The CreateDateTimeIndex method constructs an IndexT of DateTime values that contains the instances of the recurrence during a time period. This method has three overloads.

The first overload takes two or three arguments. The first argument is the start date of the time period. The second argument is the number of occurrences to include in the index. The optional third argument is a SortOrder value that specifies whether the dates should be listed in ascending or descending order. The default is ascending.

The second overload takes four arguments. The first is once again the start date. The second is the end date. The third and fourth arguments are Boolean values that specify whether the end points should be included in the index. The third overload is similar to the third. The only difference is that the second argument is a TimeSpan. The end date is calculated by adding this time span to the start date.

In the below example, we create an index containing the third Friday of each month in 2017. We use each of the overloads to create the same index three times:

var thirdFriday = Recurrence.Monthly.Friday(3);
var startDate = new DateTime(2017, 1, 1);
var index1 = thirdFriday.CreateDateTimeIndex(startDate, 12);
var endDate = new DateTime(2018, 1, 1);
var index2 = thirdFriday.CreateDateTimeIndex(startDate, endDate, false, false);
var length = TimeSpan.FromDays(365);
var index3 = thirdFriday.CreateDateTimeIndex(startDate, length, false, false);

Dim thirdFriday = Recurrence.Monthly.Friday(3)
Dim startDate = New DateTime(2017, 1, 1)
Dim index1 = thirdFriday.CreateDateTimeIndex(startDate, 12)
Dim endDate = New DateTime(2018, 1, 1)
Dim index2 = thirdFriday.CreateDateTimeIndex(startDate, endDate, False, False)
Dim length = TimeSpan.FromDays(365)
Dim index3 = thirdFriday.CreateDateTimeIndex(startDate, length, False, False)

let thirdFriday = Recurrence.Monthly.Friday(3)
let startDate = new DateTime(2017, 1, 1)
let index1 = thirdFriday.CreateDateTimeIndex(startDate, 12)
let endDate = new DateTime(2018, 1, 1)
let index2 = thirdFriday.CreateDateTimeIndex(startDate, endDate, false, false)
let length = TimeSpan.FromDays(365.0)
let index3 = thirdFriday.CreateDateTimeIndex(startDate, length, false, false)