Looper 1.0.0

Looper

Looper is a lightweight library for recurring event dates calculation. I've seen many libraries and implementations of the recurring calculations. Most of them going with for-loop over all dates until the find the matching occurrence. The for-loop in this case contributes a lot to the performance of applications. I'm not that algorithm-genius, and this is kind of a brain teaser for me - I enjoy writing/drawing my code in my textbooks. And I decided to move all of it from my textbook to GitHub.

Installation

Looper is available on NuGet.

Install-Package Looper

Use the --version option to specify a preview version to install.

Basic usage

The following code demonstrates basic usage of Looper.

Find every 3rd Thursday of each month starting from October 25th, 2020:

var effectiveDate = new DateTime(2020, 10, 25);
var weekNumbers = new[] { new WeekOfMonth(3, DayOfWeek.Thursday) };
var recurringPlan = new WeekOfMonthRecurringPlan(effectiveDate, repeatInterval: 1);

var calculator = new WeekOfMonthRecurringPlanService();

  // Thursday, November 19, 2020
var firstOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 1);

 // Thursday, January 21, 2021
var thirdOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 3);

 // Number: 3, OriginalDate: Thursday, January 21, 2021
var occurrenceOnSpecificDate = calculator.GetOccurrenceOnDate(recurringPlan, new DateTime(2021, 1, 21));

 // null
var occurrenceOnNonFallingDate = calculator.GetOccurrenceOnDate(recurringPlan, new DateTime(2021, 1, 22));

 // Number: 2, OriginalDate: Thursday, December 17, 2020
var occurrenceAfterDate = calculator.GetOccurrenceOnDate(recurringPlan, new DateTime(2020, 12, 10));

 // Number: 1, OriginalDate: Thursday, November 19, 2020
var occurrenceBeforeDate = calculator.GetOccurrenceOnDate(recurringPlan, new DateTime(2020, 12, 10));

List of supported recurring plan types:

1. Annual Recurring Plan

 // December 8th
var onDays = new DayMonthSlot[] { new DayMonthSlot(12, 8)};

 // On December 8th every 3 years effectively December 15th, 2021
var recurringPlan = new AnnualRecurringPlan(new DateTime(2021, 12, 15), 3, onDays);
var calculator = new AnnualRecurringPlanService();

 // Number: 1, OriginalDate: 2022-12-15
var occurrence = calculator.GetOccurrenceAfterDate(recurringPlan, DateTime.Now);

2. Week of Month Recurring Plan (does not support 5th day of week of a month - a brain teaser one)

var effectiveDate = new DateTime(2021, 12, 15);
// Every 3rd Thursday of a month
var weekNumbers = new[] { new WeekOfMonth(3, DayOfWeek.Thursday) };
var recurringPlan = new WeekOfMonthRecurringPlan(effectiveDate, repeatInterval: 1, weekNumbers);

var calculator = new WeekOfMonthRecurringPlanService();
// Number: 1, OriginalDate: 2021-12-16
var occurrence = calculator.GetOccurrenceByNumber(recurringPlan, 1);

3. Monthly Recurring Plan

var effectiveDate = new DateTime(2021, 12, 6);
// Every 5th and 20th days of a month
var recurringPlan = new MonthlyRecurringPlan(effectiveDate, 1, new[] { 5, 20 });
var calculator = new MonthlyRecurringPlanService();

// Monday, December 20, 2021
var firstOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 1);

// Wednesday, January 5, 2022
var secondOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 2);

// Thursday, January 20, 2022
var thirdOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 3);

// Saturday, February 5, 2022
var fourthOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 4);

4. Weekly Recurring Plan

var effectiveDate = new DateTime(2021, 12, 15);
// Every Monday, Friday and Sunday
var weekNumbers = new[] {DayOfWeek.Monday, DayOfWeek.Friday, DayOfWeek.Sunday};
var recurringPlan = new WeeklyRecurringPlan(effectiveDate, 1, weekNumbers);
var calculator = new WeeklyRecurringPlanService();

Friday, December 17, 2021
var firstOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 1);

Sunday, December 19, 2021
var secondOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 2);

Monday, December 20, 2021
var thirdOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 3);

Friday, December 24, 2021
var fourthOccurrence = calculator.GetOccurrenceByNumber(recurringPlan, 4);

5. Daily Recurring Plan