Clamp functions added to Duration and DateTime #53

Author: jogboms

lib/src/extensions.dart

@@ -224,6 +224,41 @@ extension DateTimeTimeExtension on DateTime {
 
   /// Returns the last day of this year
   DateTime get lastDayOfYear => isUtc ? DateTime.utc(year, 12, 31) : DateTime(year, 12, 31);
+
+  /// Returns this [DateTime] clamped to be in the range [min]-[max].
+  ///
+  /// The comparison is done using [compareTo].
+  ///
+  /// The arguments [min] and [max] must form a valid range where
+  /// `min.compareTo(max) <= 0`.
+  ///
+  /// Example:
+  /// ```dart
+  /// var result = DateTime(2022, DateTime.october, 15).clamp(
+  ///   min: DateTime(2022, DateTime.september, 1),
+  ///   max: DateTime(2022, DateTime.september, 30),
+  /// ); // DateTime(2022, DateTime.september, 30);
+  /// result = DateTime(2022, DateTime.august, 21).clamp(
+  ///   min: DateTime(2022, DateTime.september, 15),
+  ///   max: DateTime(2022, DateTime.september, 30),
+  /// ); // DateTime(2022, DateTime.september, 15);
+  /// result = DateTime(2022, DateTime.september, 1).clamp(
+  ///   min: DateTime(2022, DateTime.august, 1),
+  ///   max: DateTime(2022, DateTime.september, 30),
+  /// ); // DateTime(2022, DateTime.september, 1);
+  /// ```
+  DateTime clamp({DateTime? min, DateTime? max}) {
+    assert(
+      ((min != null) && (max != null)) ? min.compareTo(max).isNegative : true,
+      'DateTime min has to be before max\n(min: $min - max: $max)',
+    );
+    if ((min != null) && compareTo(min).isNegative) {
+      return min;
+    } else if ((max != null) && max.compareTo(this).isNegative) {
+      return max;
+    }
+    return this;
+  }
 }
 
 extension DurationTimeExtension on Duration {
@@ -241,4 +276,39 @@ extension DurationTimeExtension on Duration {
 
   /// Returns a Future.delayed from this
   Future<void> get delay => Future.delayed(this);
+
+  /// Returns this [Duration] clamped to be in the range [min]-[max].
+  ///
+  /// The comparison is done using [compareTo].
+  ///
+  /// The arguments [min] and [max] must form a valid range where
+  /// `min.compareTo(max) <= 0`.
+  ///
+  /// Example:
+  /// ```dart
+  /// var result = Duration(days: 10, hours: 12).clamp(
+  ///   min: Duration(days: 5),
+  ///   max: Duration(days: 10),
+  /// ); // Duration(days: 10)
+  /// result = Duration(hours: 18).clamp(
+  ///   min: Duration(days: 5),
+  ///   max: Duration(days: 10),
+  /// ); // Duration(days: 5)
+  /// result = Duration(days: 0).clamp(
+  ///   min: Duration(days: -5),
+  ///   max: Duration(days: 5),
+  /// ); // Duration(days: 0)
+  /// ```
+  Duration clamp({Duration? min, Duration? max}) {
+    assert(
+      ((min != null) && (max != null)) ? min.compareTo(max).isNegative : true,
+      'Duration min has to be shorter than max\n(min: $min - max: $max)',
+    );
+    if ((min != null) && compareTo(min).isNegative) {
+      return min;
+    } else if ((max != null) && max.compareTo(this).isNegative) {
+      return max;
+    }
+    return this;
+  }
 }

test/time_test.dart

@@ -547,7 +547,7 @@ void main() {
           expect(initial.firstDayOfMonth, expected);
         });
 
-        group('last day of month', (){
+        group('last day of month', () {
           test('last day of month', () {
             final initial = DateTime(2022, 5, 20);
             final expected = DateTime(2022, 5, 31);
@@ -564,7 +564,6 @@ void main() {
             final expected = DateTime(2020, 2, 29);
             expect(initial.lastDayOfMonth, expected);
           });
-
         });
 
         test('first day of year', () {
@@ -580,6 +579,68 @@ void main() {
         });
       });
     });
+
+    group('clamp', () {
+      group('returns max when before it', () {
+        final it = DateTime(2022, DateTime.october, 15);
+        final min = DateTime(2022, DateTime.september, 1);
+        final max = DateTime(2022, DateTime.september, 30);
+
+        test('when it has a value for min', () {
+          expect(it.clamp(min: min, max: max), equals(max));
+        });
+
+        test('when it does not have a value for min', () {
+          expect(it.clamp(max: max), equals(max));
+        });
+      });
+
+      group('returns min when after it', () {
+        final it = DateTime(2022, DateTime.august, 21);
+        final min = DateTime(2022, DateTime.september, 15);
+        final max = DateTime(2022, DateTime.september, 30);
+
+        test('when it has a value for max', () {
+          expect(it.clamp(min: min, max: max), equals(min));
+        });
+
+        test('when it does not have a value for max', () {
+          expect(it.clamp(min: min), equals(min));
+        });
+      });
+
+      group('returns it', () {
+        final it = DateTime(2022, DateTime.september, 1);
+        final min = DateTime(2022, DateTime.august, 1);
+        final max = DateTime(2022, DateTime.september, 30);
+
+        test('when both min and max are null', () {
+          expect(it.clamp(), equals(it));
+        });
+
+        test('when is longer than min and max is null', () {
+          expect(it.clamp(min: min), equals(it));
+        });
+
+        test('when is shorter than max and min is null', () {
+          expect(it.clamp(max: max), equals(it));
+        });
+
+        test('when is longer than min and shorter than max', () {
+          expect(it.clamp(min: min, max: max), equals(it));
+        });
+      });
+
+      test('asserts that min should be before max', () {
+        final it = DateTime(2022, DateTime.september, 1);
+        final min = DateTime(2022, DateTime.september, 30);
+        final max = DateTime(2022, DateTime.august, 1);
+        expect(
+          () => it.clamp(min: min, max: max),
+          throwsA(isA<AssertionError>()),
+        );
+      });
+    });
   });
 
   group('Duration', () {
@@ -615,5 +676,67 @@ void main() {
       final extraTime = after.millisecondsSinceEpoch - before.add(timeToWait).millisecondsSinceEpoch;
       expect(extraTime >= 0, true);
     });
+
+    group('clamp', () {
+      group('returns max when shorter than it', () {
+        final it = Duration(days: 10, hours: 12);
+        final min = Duration(days: 5);
+        final max = Duration(days: 10);
+
+        test('when it has a value for min', () {
+          expect(it.clamp(min: min, max: max), equals(max));
+        });
+
+        test('when it does not have a value for min', () {
+          expect(it.clamp(max: max), equals(max));
+        });
+      });
+
+      group('returns min when longer than it', () {
+        final it = Duration(hours: 18);
+        final min = Duration(days: 5);
+        final max = Duration(days: 10);
+
+        test('when it has a value for max', () {
+          expect(it.clamp(min: min, max: max), equals(min));
+        });
+
+        test('when it does not have a value for max', () {
+          expect(it.clamp(min: min), equals(min));
+        });
+      });
+
+      group('returns it', () {
+        final it = Duration(days: 0);
+        final min = Duration(days: -5);
+        final max = Duration(days: 5);
+
+        test('when both min and max are null', () {
+          expect(it.clamp(), equals(it));
+        });
+
+        test('when is longer than min and max is null', () {
+          expect(it.clamp(min: min), equals(it));
+        });
+
+        test('when is shorter than max and min is null', () {
+          expect(it.clamp(max: max), equals(it));
+        });
+
+        test('when is longer than min and shorter than max', () {
+          expect(it.clamp(min: min, max: max), equals(it));
+        });
+      });
+
+      test('asserts that min should be shorter than max', () {
+        final it = Duration(days: -0);
+        final min = Duration(days: 5);
+        final max = Duration(days: -5);
+        expect(
+          () => it.clamp(min: min, max: max),
+          throwsA(isA<AssertionError>()),
+        );
+      });
+    });
   });
 }