Periods and DateValidators

CHANGELOG.md

@@ -1,3 +1,15 @@
+# 2.0.0 - 2023.03.28
+
+- Added [DateValidator] and some implementations.
+- Implemented [DateValidator] in all implementations of [Every].
+- Created [Period] and some implementations.
+- Created [PeriodGeneratorMixin] and some implementations.
+
+## Breaking changes
+
+- API changes to always use optional named parameters.
+- API changes replacing optional positional parameters for optional named parameters.
+
 # 1.0.4 - 2022.08.23
 
 - Fixed typo on changelog.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 FELIPE EDUARDO MORSCHEL
+Copyright (c) 2022 FMORSCHEL
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,33 +1,76 @@
 # DueDate
 
-A package for working with repeating DateTime patterns.
+A package for working with repeating `DateTime` patterns.
 
-Ever wanted to create a new DateTime with, let's say, the same day in month? But the day is 31 and next month only has 30, so you go to 30 and the next day is lost because then you have no variable to save the original's month day? With DueDateTime this managing is done for you without any headaches.
+Ever wanted to create a new `DateTime` with, let's say, the same day in month? But the day is 31 and next month only has 30, so you go to 30 and the next day is lost because then you have no variable to save the original's month day? With `DueDateTime` this managing is done for you without any headaches.
+
+Or maybe you have to check if some `DateTime` is inside a certain period of time and always have to manually get, let's say, the start and end of the week and process it yourself. Now you can use `PeriodGenerator`s and `Period` methods to work it out for you.
 
 ## Features
 
 Examples of what this package can do:
 
+### DueDateTime
+
 ```dart
 final date = DateTime(2022, DateTime.january, 31);
 DueDateTime dueDate = DueDateTime.fromDate(date);
 dueDate = dueDate.addMonths(1); // February 28th, 2022
 dueDate = dueDate.addMonths(1); // March 31th, 2022
 ```
 
+### Period
+
+```dart
+final period1 = Period(
+  start: DateTime(2022, DateTime.january, 1),
+  end: DateTime(2022, DateTime.january, 5),
+);
+final period2 = Period(
+  start: DateTime(2022, DateTime.january, 3),
+  end: DateTime(2022, DateTime.january, 7),
+);
+if (period1.overlapsWith(period2)) {
+  print('The two periods overlap.');
+} else {
+  print('The two periods do not overlap.');
+}
+```
+
+### PeriodGenerator
+
+```dart
+final hourGenerator = HourGenerator();
+final secondGenerator = SecondGenerator();
+final now = DateTime.now();
+final currentHour = hourGenerator.of(now);
+final currentSecond = secondGenerator.of(now);
+print('The current hour is $currentHour.');
+print('The current second is $currentSecond.');
+final nextHour = currentHour.getNext(hourGenerator);
+final nextSecond = currentSecond.getNext(secondGenerator);
+print('The next hour is $nextHour.');
+print('The next second is $nextSecond.');
+final previousHour = currentHour.getPrevious(hourGenerator);
+final previousSecond = currentSecond.getPrevious(secondGenerator);
+print('The previous hour is $previousHour.');
+print('The previous second is $previousSecond.');
+```
+
 ## Getting started
 
 On your `pubspec.yaml` file, add this package to your dependencies:
 
 ```yaml
   dependencies:
-    due_date: ^1.0.4
+    due_date: ^2.0.0
 ```
 
-Import the package library on your code:
+Import one of the, or both, package libraries on your code:
 
 ```dart
 import 'package:due_date/due_date.dart';
+import 'package:due_date/period.dart';
 ```
 
 ## Usage

analysis_options.yaml

@@ -8,11 +8,64 @@ analyzer:
     strict-inference: true
     strict-raw-types: true
   exclude:
-    - "**generated_plugin_registrant.dart"
-    - "lib/src/database/database.g.dart"
+    - "**/generated_plugin_registrant.dart"
   errors:
     missing_required_param: error
 
+dart_code_metrics:
+  rules:
+    - double-literal-format
+    - format-comment
+    - member-ordering-extended:
+        alphabetize: false
+        order:
+          - constructors
+          - named-constructors
+          - factory-constructors
+          - static-getters-setters
+          - static-const-public-fields
+          - static-const-private-fields
+          - static-final-public-fields
+          - static-final-private-fields
+          - static-late-final-public-fields
+          - static-late-final-private-fields
+          - static-late-public-fields
+          - static-late-private-fields
+          - static-public-fields
+          - static-private-fields
+          - const-public-fields
+          - const-private-fields
+          - final-public-fields
+          - final-private-fields
+          - late-final-public-fields
+          - late-final-private-fields
+          - late-public-fields
+          - late-private-fields
+          - public-fields
+          - private-fields
+          - overridden-public-fields
+          - overriden-public-methods
+          - static-public-methods
+          - static-private-methods
+          - public-methods
+          - private-methods
+          - getters-setters
+    - prefer-commenting-analyzer-ignores
+    - prefer-first
+    - prefer-immediate-return
+    - prefer-last
+
+    - always-remove-listener
+    - avoid-border-all
+    - avoid-returning-widgets:
+        ignored-names:
+          - testFunction
+        ignored-annotations:
+          - allowedAnnotation
+    - avoid-unnecessary-setstate
+    - avoid-wrapping-in-padding
+    - prefer-const-border-radius
+
 linter:
   rules:
     always_declare_return_types: true
@@ -83,57 +136,3 @@ linter:
     use_test_throws_matchers: true
     use_to_and_as_if_applicable: true
     void_checks: true
-
-dart_code_metrics:
-  rules:
-    - always-remove-listener
-    - avoid-border-all
-    - avoid-returning-widgets:
-        ignored-names:
-          - testFunction
-        ignored-annotations:
-          - allowedAnnotation
-    - avoid-unnecessary-setstate
-    - avoid-wrapping-in-padding
-    - prefer-const-border-radius
-
-    - double-literal-format
-    - format-comment
-    - prefer-commenting-analyzer-ignores
-    - prefer-first
-    - prefer-immediate-return
-    - prefer-last
-    - member-ordering-extended:
-        alphabetize: false
-        order:
-          - constructors
-          - named-constructors
-          - factory-constructors
-          - static-getters-setters
-          - static-const-public-fields
-          - static-const-private-fields
-          - static-final-public-fields
-          - static-final-private-fields
-          - static-late-final-public-fields
-          - static-late-final-private-fields
-          - static-late-public-fields
-          - static-late-private-fields
-          - static-public-fields
-          - static-private-fields
-          - const-public-fields
-          - const-private-fields
-          - final-public-fields
-          - final-private-fields
-          - late-final-public-fields
-          - late-final-private-fields
-          - late-public-fields
-          - late-private-fields
-          - public-fields
-          - private-fields
-          - overridden-public-fields
-          - overriden-public-methods
-          - static-public-methods
-          - static-private-methods
-          - public-methods
-          - private-methods
-          - getters-setters

example/bin/example.dart

@@ -1,6 +1,9 @@
 import 'package:due_date/due_date.dart';
+import 'package:due_date/period.dart';
 
 void main(List<String> arguments) {
+  /// DueDateTime.
+
   final date = DateTime(2022, DateTime.january, 31);
   DueDateTime dueDate = date.dueDateTime;
   print(dueDate.toString()); // 2022-01-31
@@ -21,4 +24,45 @@ void main(List<String> arguments) {
   print(dueDate2.toString()); // 2022-03-25
   dueDate2 = dueDate2.next();
   print(dueDate2.toString()); // 2022-04-29
+
+  /// Period.
+
+  final period1 = Period(
+    start: DateTime(2022, DateTime.january, 1),
+    end: DateTime(2022, DateTime.january, 5),
+  );
+  final period2 = Period(
+    start: DateTime(2022, DateTime.january, 3),
+    end: DateTime(2022, DateTime.january, 7),
+  );
+
+  if (period1.overlapsWith(period2)) {
+    print('The two periods overlap.');
+  } else {
+    print('The two periods do not overlap.');
+  }
+
+  /// PeriodGenerators.
+
+  final hourGenerator = HourGenerator();
+  final secondGenerator = SecondGenerator();
+
+  final now = DateTime.now();
+  final currentHour = hourGenerator.of(now);
+  final currentSecond = secondGenerator.of(now);
+
+  print('The current hour is $currentHour.');
+  print('The current second is $currentSecond.');
+
+  final nextHour = currentHour.getNext(hourGenerator);
+  final nextSecond = currentSecond.getNext(secondGenerator);
+
+  print('The next hour is $nextHour.');
+  print('The next second is $nextSecond.');
+
+  final previousHour = currentHour.getPrevious(hourGenerator);
+  final previousSecond = currentSecond.getPrevious(secondGenerator);
+
+  print('The previous hour is $previousHour.');
+  print('The previous second is $previousSecond.');
 }

lib/due_date.dart

@@ -2,7 +2,7 @@
 ///
 /// This package is used to create custom due dates.
 ///
-/// Implementing your own DueDateTime is easy. You implement an [Every]
+/// Implementing your own [DueDateTime] is easy. You implement an [Every]
 /// class and pass it to the [DueDateTime] constructor.
 ///
 /// There are already some [Every] classes implemented in this package. Look for
@@ -25,6 +25,14 @@ library due_date;
 
 export 'src/date_validator.dart';
 export 'src/due_date.dart';
-export 'src/enums.dart';
+export 'src/enums.dart' show Weekday, Month, Week, WeekdayOccurrence;
 export 'src/every.dart';
-export 'src/extensions.dart';
+export 'src/extensions.dart'
+    show
+        DayInYear,
+        AddDays,
+        WeekCalc,
+        ClampInMonth,
+        PreviousNext,
+        DateValidatorListExt,
+        EveryDateValidatorListExt;

lib/period.dart

@@ -0,0 +1,22 @@
+/// Support for creating your own custom periods.
+///
+/// This package is used to create custom periods.
+///
+/// Implementing your own [Period] or [PeriodGenerator] is easy.
+///
+/// There are already some [Period] classes implemented in this package. Look
+/// for [SecondPeriod], [MinutePeriod], [HourPeriod], [DayPeriod], [WeekPeriod],
+/// [FortnightPeriod], [MonthPeriod], [TrimesterPeriod], [SemesterPeriod] and
+/// [YearPeriod].
+///
+/// There are already some [PeriodGenerator] classes implemented in this
+/// package. Look for [SecondGenerator], [MinuteGenerator],
+/// [HourGenerator], [DayGenerator], [WeekGenerator],
+/// [FortnightGenerator], [MonthGenerator], [TrimesterGenerator],
+/// [SemesterGenerator] and [YearGenerator].
+library period;
+
+export 'src/enums.dart' show Weekday, Month, Week, PeriodGenerator;
+export 'src/extensions.dart' show EndOfDay;
+export 'src/period.dart';
+export 'src/period_generator.dart';

lib/src/date_validator.dart

@@ -6,6 +6,7 @@ import '../due_date.dart';
 
 /// A class to save a specific validation for a [DateTime].
 abstract class DateValidator {
+  /// A class to save a specific validation for a [DateTime].
   const DateValidator();
 
   /// Returns true if the [date] is valid for this [DateValidator].
@@ -250,6 +251,7 @@ class DateValidatorDayInYear extends DateValidator
   List<Object> get props => [dayInYear];
 }
 
+/// Mixin that represents a list of [DateValidator]s.
 mixin DateValidatorListMixin<E extends DateValidator> on List<E>
     implements DateValidator {
   /// List for all of the [validators] that will be used to validate the date.
@@ -286,6 +288,8 @@ class DateValidatorIntersection<E extends DateValidator>
 /// of the [validators].
 class DateValidatorUnion<E extends DateValidator> extends DelegatingList<E>
     with EquatableMixin, DateValidatorMixin, DateValidatorListMixin {
+  /// A [DateValidator] that validates a [DateTime] if the date is valid for any
+  /// of the [validators].
   const DateValidatorUnion(super.validators);
 
   @override
@@ -308,6 +312,8 @@ class DateValidatorUnion<E extends DateValidator> extends DelegatingList<E>
 /// one of the [validators].
 class DateValidatorDifference<E extends DateValidator> extends DelegatingList<E>
     with EquatableMixin, DateValidatorMixin, DateValidatorListMixin {
+  /// A [DateValidator] that validates a [DateTime] if the date is valid for only
+  /// one of the [validators].
   const DateValidatorDifference(super.validators);
 
   @override