Refactors occurrences extensions with date filtering (#16)

* refactors inRange extension to occurrences with optional date range parameters
* updates readme

Author: Koen Zwikstra

README.md

@@ -16,7 +16,8 @@ A Dart library for parsing and working with iCalendar (.ics) files. Built with R
   - [Working with Timezones](#working-with-timezones)
   - [Recurring Events](#recurring-events)
   - [Filtering Events by Date Range](#filtering-events-by-date-range)
-  - [Chronological ordering across multiple events](#chronological-ordering-across-multiple-events)
+  - [Getting All Occurrences](#getting-all-occurrences)
+  - [Chronological Ordering Across Multiple Events](#chronological-ordering-across-multiple-events)
   - [Streaming Large Files](#streaming-large-files)
   - [Conditional Parsing with Stream Parser](#conditional-parsing-with-stream-parser)
   - [Custom Property Parsers](#custom-property-parsers)
@@ -87,6 +88,12 @@ print('Summary: ${event.summary ?? "Untitled"}');
 print('Location: ${event.location ?? "No location"}');
 print('Description: ${event.description ?? ""}');
 
+// Extension properties
+print('Is recurring: ${event.isRecurring}');
+print('Is all-day: ${event.isAllDay}');
+print('Is multi-day: ${event.isMultiDay}');
+print('Duration: ${event.effectiveDuration}');
+
 // Attendees
 for (final attendee in event.attendees) {
   print('Attendee: ${attendee.address}');
@@ -144,26 +151,45 @@ for (final occurrence in event.occurrences().take(10)) {
 
 ### Filtering Events by Date Range
 
-Use the `inRange` extension to filter events that occur within a specific date range. This works correctly with multi-day events, all-day events, and recurring events. Results are always returned in chronological order, regardless of the order in the source file.
+Use the `occurrences` extension to filter events that occur within a specific date range. This works correctly with multi-day events, all-day events, and recurring events. Results are always returned in chronological order, regardless of the order in the source file.
 
 ```dart
 final start = CalDateTime.date(2024, 3, 1);
 final end = CalDateTime.date(2024, 3, 31);
 
 // Get all event occurrences in March 2024
-final occurrencesInMarch = calendar.events.inRange(start, end);
+final occurrencesInMarch = calendar.events.occurrences(
+  start: start,
+  end: end,
+);
 
 for (final result in occurrencesInMarch) {
   print('${result.event.summary}: ${result.occurrence}');
 }
 
 // Works with todos and journals too
-final todoOccurrences = calendar.todos.inRange(start, end);
+final todoOccurrences = calendar.todos.occurrences(
+  start: start,
+  end: end,
+);
+```
+
+### Getting All Occurrences
+
+When you need all occurrences across multiple components without filtering by date range, simply call `occurrences()` without parameters. Use `.take()` to limit results when working with recurring events that could generate infinite occurrences.
+
+```dart
+// Get all occurrences without date filtering
+final allOccurrences = calendar.events.occurrences();
+
+for (final result in allOccurrences.take(20)) {
+  print('${result.event.summary}: ${result.occurrence}');
+}
 ```
 
-### Chronological ordering across multiple events
+### Chronological Ordering Across Multiple Events
 
-The `inRange` extension automatically sorts event occurrences chronologically, regardless of the order they appear in the source iCalendar file.
+The `occurrences` extension automatically sorts event occurrences chronologically, regardless of the order they appear in the source iCalendar file.
 
 ```dart
 final ics = '''
@@ -197,7 +223,10 @@ final calendar = parser.parseFromString(ics);
 final start = CalDateTime.date(2024, 3, 1);
 final end = CalDateTime.date(2024, 3, 31);
 
-for (final result in calendar.events.inRange(start, end)) {
+for (final result in calendar.events.occurrences(
+  start: start,
+  end: end,
+)) {
   print('${result.occurrence}: ${result.event.summary}');
 }
 

lib/src/semantic/extensions/calendar_types.dart

@@ -26,13 +26,7 @@ extension CalDateTimeExtensions on CalDateTime {
 
   /// The day of the year (1-365 or 1-366 in leap years).
   int get dayOfYear {
-    final startOfYear = copyWith(
-      month: 1,
-      day: 1,
-      hour: 0,
-      minute: 0,
-      second: 0,
-    );
+    final startOfYear = CalDateTime.date(year, 1, 1);
     return native.difference(startOfYear.native).inDays + 1;
   }
 

lib/src/semantic/extensions/components.dart

@@ -97,8 +97,10 @@ extension EventComponentExtensions on EventComponent {
   /// Generates all occurrences of the event based on its recurrence
   /// rules, exclusions (EXDATE), and additional dates (RDATE).
   ///
+  /// [start] and [end] can be provided to limit the occurrences.
+  ///
   /// Returns an empty iterable if the event has no start date.
-  Iterable<CalDateTime> occurrences() {
+  Iterable<CalDateTime> occurrences({CalDateTime? start, CalDateTime? end}) {
     if (dtstart == null) return const Iterable<CalDateTime>.empty();
 
     final iterator = RecurrenceIterator(
@@ -107,7 +109,11 @@ extension EventComponentExtensions on EventComponent {
       exdates: exdates,
       rdates: rdates,
     );
-    return iterator.occurrences();
+    return iterator.occurrences(
+      start: start,
+      end: end,
+      duration: effectiveDuration,
+    );
   }
 }
 
@@ -156,8 +162,10 @@ extension TodoComponentExtensions on TodoComponent {
   /// Generates all occurrences of the todo based on its recurrence
   /// rules, exclusions (EXDATE), and additional dates (RDATE).
   ///
+  /// [start] and [end] can be provided to limit the occurrences.
+  ///
   /// Returns an empty iterable if the todo has no start date.
-  Iterable<CalDateTime> occurrences() {
+  Iterable<CalDateTime> occurrences({CalDateTime? start, CalDateTime? end}) {
     if (dtstart == null) return const Iterable<CalDateTime>.empty();
 
     final iterator = RecurrenceIterator(
@@ -166,7 +174,11 @@ extension TodoComponentExtensions on TodoComponent {
       exdates: exdates,
       rdates: rdates,
     );
-    return iterator.occurrences();
+    return iterator.occurrences(
+      start: start,
+      end: end,
+      duration: effectiveDuration,
+    );
   }
 }
 
@@ -179,8 +191,10 @@ extension JournalComponentExtensions on JournalComponent {
   /// Generates all occurrences of the journal based on its recurrence
   /// rules, exclusions (EXDATE), and additional dates (RDATE).
   ///
+  /// [start] and [end] can be provided to limit the occurrences.
+  ///
   /// Returns an empty iterable if the journal has no start date.
-  Iterable<CalDateTime> occurrences() {
+  Iterable<CalDateTime> occurrences({CalDateTime? start, CalDateTime? end}) {
     if (dtstart == null) return const Iterable<CalDateTime>.empty();
 
     final iterator = RecurrenceIterator(
@@ -189,7 +203,7 @@ extension JournalComponentExtensions on JournalComponent {
       exdates: exdates,
       rdates: rdates,
     );
-    return iterator.occurrences();
+    return iterator.occurrences(start: start, end: end);
   }
 }
 
@@ -201,13 +215,15 @@ extension TimeZoneSubComponentExtensions on TimeZoneSubComponent {
 
   /// Generates all occurrences of the timezone component based on its recurrence
   /// rules, exclusions (EXDATE), and additional dates (RDATE).
-  Iterable<CalDateTime> occurrences() {
+  ///
+  /// [start] and [end] can be provided to limit the occurrences.
+  Iterable<CalDateTime> occurrences({CalDateTime? start, CalDateTime? end}) {
     final iterator = RecurrenceIterator(
       dtstart: dtstart,
       rrule: rrule,
       rdates: rdates,
     );
-    return iterator.occurrences();
+    return iterator.occurrences(start: start, end: end);
   }
 }