v2.5.0

Author: omar-hanafy

CHANGELOG.md

@@ -1,9 +1,29 @@
 # CHANGELOG
+## [2.5.0]
+- Added `castTo<R>()` to the List and Set extensions and `toListCasted<R>()` & `toSetCasted<R>()` to the Iterable extension.
+- Enhanced numeric extensions with additional date-related helpers:
+  - Added helpers to check if the number matches the current year, month, day of the month, or day of the week: `isCurrentYear`, `isCurrentMonth`, `isCurrentDay`, and `isCurrentDayOfWeek`.
+  - `isBetweenMonths`: Checks if a number (representing a month) falls within a specified range, handling year boundaries gracefully.
+- Added `isInThisMonth` in the date extension, it checks if a month of this date matches the month of now.
+- Updated some docs.
+
+```dart
+void main()  {
+  final list = [1, 2, '3', '3.1', 22.3];
+  
+  // Parsing a dynamic numeric list to num, int, and double.
+  print(list.castTo<num>()); // [1, 2, 3, 3.1, 22.3]
+  print(list.castTo<int>()); // [1, 2, 3, 3, 22]
+  print(list.castTo<double>()); // [1.0, 2.0, 3.0, 3.1, 22.3]
+}
+```
 ## [2.4.0]
 ### New Features
-**`totalBy` Getter:** The `totalBy` getter as an extension on any `Iterable`. It allows you to calculate the total of a specific numeric property within the objects of the iterable by providing a selector function.
-**`total` Getter:** Now, any `Iterable` containing numeric types (`int?`, `double?`, `num?`) has access to a `total` getter. This getter computes the sum of all numeric elements within the iterable, with null values being treated as zeros
-**`nodesWhere` in `DoublyLinkedList`** The `DoublyLinkedList` now includes a `nodesWhere` method, which returns all nodes that satisfy a given condition specified by the test function `bool Function(Node<E>)`.
+**`total` on `Iterable<num>`:** This getter computes the sum of all numeric elements within the iterable, with null values being treated as zeros
+
+**`totalBy` on `Iterable<E>`:** Allows you to calculate the total of a specific numeric property within the objects of the iterable by providing a selector function.
+
+**`nodesWhere` on `DoublyLinkedList`** The `DoublyLinkedList` now includes a `nodesWhere` method, which returns all nodes that satisfy a given condition specified by the test function `bool Function(Node<E>)`.
 
 ```dart
 num totalPrice = productList.totalBy((product) => product?.price);

README.md

@@ -2,7 +2,7 @@
 
 [![pub package](https://img.shields.io/pub/v/dart_helper_utils)](https://pub.dev/packages/dart_helper_utils)
 
-The `dart_helper_utils` package provides a collection of Dart utilities, tools for converting dynamic objects to various types, and extending core Dart classes with extension.
+The `dart_helper_utils` package provides a collection of Dart utilities, tools for converting dynamic objects to various types, and extending core Dart classes with an extension.
 
 **Note:** This package is tailored for Dart projects. For Flutter projects, use [`flutter_helper_utils`](https://pub.dev/packages/flutter_helper_utils), which includes all `dart_helper_utils` features plus additional utilities and extension for Flutter, such as `Widget`, `Color`, and `BuildContext` extension.
 
@@ -58,16 +58,16 @@ The `DoublyLinkedList` class offers a way to manage ordered collections of data
 
 **Key Advantages:**
 * **Efficient Insertion/Deletion:** Adding or removing elements at the beginning, middle, or end of the list takes constant time (O(1)).
-* **Bidirectional Traversal:**  Easily navigate through the list in either direction using the `next` and `prev` references on each node.
+* **Bidirectional Traversal:** Easily navigate through the list in either direction using the `next` and `prev` references on each node.
 * **Memory Flexibility:** The list dynamically grows or shrinks as needed, making it memory-efficient for managing collections of varying sizes.
 
 **Core Features:**
-* **List-Like Interface:**  You can use `DoublyLinkedList` just like a standard Dart `List`, with familiar methods like `add`, `insert`, `remove`, `clear`, etc.
+* **List-Like Interface:** You can use `DoublyLinkedList` just like a standard Dart `List`, with familiar methods like `add`, `insert`, `remove`, `clear`, etc.
 * **Node Iteration:** The `nodes` property provides a convenient way to iterate over the individual nodes of the list, giving you access to `data`, `prev`, and `next` fields.
 * **Factory Constructors:** Easily create lists with specific characteristics:
   - `filled(length, fill)`: Creates a list of a given length filled with a specified value.
   - `generate(length, generator)`: Creates a list by applying a function to generate elements.
-  - `from(Iterable)`: Creates a list from an existing iterable.
+  - `from(Iterable)`: Creates a list from existing iterable.
 
 **Example Usage:**
 ```dart

example/dart_helper_utils_example.dart

@@ -1,6 +1,12 @@
 import 'package:dart_helper_utils/dart_helper_utils.dart';
 
 Future<void> main() async {
+  // parsing dynamic numeric list to num, int, and double.
+  final list = [1, 2, '3', '3.1', 22.3];
+  print(list.castTo<num>()); // [1, 2, 3, 3.1, 22.3]
+  print(list.castTo<int>()); // [1, 2, 3, 3, 22]
+  print(list.castTo<double>()); // [1.0, 2.0, 3.0, 3.1, 22.3]
+
   // parsing raw Json array of doubles to List<int>
   final intList = tryToList<int>('[1.5, 2.3, 3.4]');
   print(intList); // [1, 2, 3]

lib/src/extensions/date.dart

@@ -2,6 +2,8 @@ import 'dart:io';
 
 import 'package:dart_helper_utils/dart_helper_utils.dart';
 
+int get millisecondsSinceEpochNow => DateTime.now().millisecondsSinceEpoch;
+
 extension DHUDateString on String {
   /// Parse string to [DateTime] using null Safety
   DateTime get toDateTime => DateTime.parse(this);
@@ -27,8 +29,15 @@ extension DHUDateNullString on String? {
   }
 }
 
-extension NumberToDateNames on num {
+extension NumberToDateUtils on num {
   /// Gets the full month name (e.g., "January") corresponding to this number (1-12).
+  ///
+  /// Example:
+  /// ```dart
+  /// 1.toFullMonthName; // Returns "January"
+  /// 12.toFullMonthName; // Returns "December"
+  /// ```
+  /// If the number is outside the range 1-12, it will be clamped within this range.
   String get toFullMonthName {
     final monthIndex = this.toInt().clamp(1, 12) - 1;
     return [
@@ -48,6 +57,15 @@ extension NumberToDateNames on num {
   }
 
   /// Gets the full day name (e.g., "Monday") corresponding to this number (1-7).
+  ///
+  /// This method follows ISO 8601, where the week starts on Monday (1) and ends on Sunday (7).
+  ///
+  /// Example:
+  /// ```dart
+  /// 1.toFullDayName; // Returns "Monday"
+  /// 7.toFullDayName; // Returns "Sunday"
+  /// ```
+  /// If the number is outside the range 1-7, it will be normalized within this range using modulo arithmetic.
   String get toFullDayName {
     final dayIndex = (this.toInt() - 1) % 7; // Ensure value is within 0-6
     return [
@@ -62,27 +80,142 @@ extension NumberToDateNames on num {
   }
 
   /// Gets the short day name (e.g., "Mon") corresponding to this number (1-7).
+  ///
+  /// Example:
+  /// ```dart
+  /// 1.toSmallDayName; // Returns "Mon"
+  /// 7.toSmallDayName; // Returns "Sun"
+  /// ```
+  /// If the number is outside the range 1-7, it will be normalized within this range using modulo arithmetic.
   String get toSmallDayName => toFullDayName.substring(0, 3);
 
   /// Gets the short month name (e.g., "Jan") corresponding to this number (1-12).
+  ///
+  /// Example:
+  /// ```dart
+  /// 1.toSmallMonthName; // Returns "Jan"
+  /// 12.toSmallMonthName; // Returns "Dec"
+  /// ```
+  /// If the number is outside the range 1-12, it will be clamped within this range.
   String get toSmallMonthName => toFullMonthName.substring(0, 3);
 
-  // convert all to int and if the number is too large for month def is 12 if too small def is 1 and so on
+  /// Converts a numeric timestamp (in milliseconds since epoch) to a DateTime object.
+  ///
+  /// Example:
+  /// ```dart
+  /// 1609459200000.timestampToDate; // Returns DateTime for 2021-01-01 00:00:00.000
+  /// ```
   DateTime get timestampToDate =>
       DateTime.fromMillisecondsSinceEpoch(this.toInt());
+
+  /// Checks if the number (assumed to represent a month, 1-based) is within the specified range of months.
+  ///
+  /// This method handles ranges that cross the year boundary (e.g., December to February).
+  ///
+  /// Example:
+  /// ```dart
+  /// 3.isBetweenMonths(12, 2); // Returns true, March is within December-February
+  /// 6.isBetweenMonths(3, 8);  // Returns true, June is within March-August
+  /// ```
+  bool isBetweenMonths(int startMonth, int endMonth) {
+    final month = this.toInt();
+    // Handle cases where the range crosses over the year boundary (e.g., December to February)
+    if (startMonth > endMonth) {
+      return month >= startMonth || month <= endMonth;
+    } else {
+      return month >= startMonth && month <= endMonth;
+    }
+  }
+
+  /// Checks if the number (assumed to represent a day of the week, 1-based) corresponds to the current day of the week.
+  ///
+  /// This method follows ISO 8601, where the week starts on Monday (1) and ends on Sunday (7).
+  ///
+  /// Example:
+  /// ```dart
+  /// 1.isCurrentDayOfWeek; // Returns true if today is Monday
+  /// 7.isCurrentDayOfWeek; // Returns true if today is Sunday
+  /// ```
+  bool get isCurrentDayOfWeek {
+    final now = DateTime.now();
+    return this.toInt() == now.weekday;
+  }
+
+  /// Checks if the number (assumed to represent a year) corresponds to the current year.
+  ///
+  /// Example:
+  /// ```dart
+  /// 2024.isCurrentYear; // Returns true if the current year is 2024
+  /// ```
+  bool get isCurrentYear {
+    final now = DateTime.now();
+    return this.toInt() == now.year;
+  }
+
+  /// Checks if the number (assumed to represent a month, 1-based) corresponds to the current month.
+  ///
+  /// Example:
+  /// ```dart
+  /// 8.isCurrentMonth; // Returns true if the current month is August
+  /// ```
+  bool get isCurrentMonth {
+    final now = DateTime.now();
+    return this.toInt() == now.month;
+  }
+
+  /// Checks if the number (assumed to represent a day, 1-based) corresponds to the current day of the month.
+  ///
+  /// Example:
+  /// ```dart
+  /// 15.isCurrentDay; // Returns true if today is the 15th of the month
+  /// ```
+  bool get isCurrentDay {
+    final now = DateTime.now();
+    return this.toInt() == now.day;
+  }
 }
 
 extension DHUNullableDateExtensions on DateTime? {
   DateTime? get local => this?.toLocal();
 
   String? get toUtcIso => this?.toUtc().toIso8601String();
 
-  bool get isTomorrow => remainingDays == 1;
+  bool get isTomorrow {
+    if (this == null) return false;
+    final now = DateTime.now();
+
+    // Quick check to rule out dates that are far away
+    if (this!.year != now.year || this!.month != now.month) {
+      return false;
+    }
+
+    return remainingDays == 1;
+  }
 
   /// return true if the date is today
-  bool get isToday => remainingDays == 0;
+  bool get isToday {
+    if (this == null) return false;
+    final now = DateTime.now();
 
-  bool get isYesterday => passedDays == 1;
+    // Quick check to rule out dates that are far away
+    if (this!.year != now.year || this!.month != now.month) {
+      return false;
+    }
+
+    return remainingDays == 0;
+  }
+
+  bool get isYesterday {
+    if (this == null) return false;
+    final now = DateTime.now();
+
+    // Quick check to rule out dates that are far away
+    if (this!.year != now.year || this!.month != now.month) {
+      return false;
+    }
+
+    return passedDays == 1;
+  }
 
   bool get isPresent => isNotNull && this!.isAfter(DateTime.now());
 
@@ -96,6 +229,12 @@ extension DHUNullableDateExtensions on DateTime? {
 
   bool get isInThisYear => isNotNull && this!.year == DateTime.now().year;
 
+  bool get isInThisMonth {
+    if (isNull) return false;
+    final now = DateTime.now();
+    return this!.month == now.month && this!.year == now.year;
+  }
+
   bool get isLeapYear {
     if (isNull) return false;
     return (this!.year % 4 == 0) &&
@@ -447,3 +586,12 @@ abstract class DatesHelper {
   static Iterable<DateTime> daysInRange(DateTime start, DateTime end) =>
       start.daysUpTo(end);
 }
+
+/*
+**Areas for Improvement**
+
+* **Error Handling:** Consider adding more robust error handling, especially in the parsing extensions, to provide informative messages to the user or log errors appropriately.
+* **Documentation:** While the code is generally well-organized, adding more detailed comments or docstrings, especially for complex functions, would improve its understandability and maintainability.
+* **Naming Conventions:** Some function names (e.g., `addOrRemoveYears`) could be more concise or descriptive.
+* **Testing:** Writing unit tests to cover various scenarios and edge cases would ensure the correctness and reliability of the code.
+*/

lib/src/extensions/iterable.dart

@@ -50,6 +50,25 @@ Would you like any specific implementation details or examples for any of these
 typedef IndexedPredicate<T> = bool Function(int index, T);
 typedef Predicate<T> = bool Function(T);
 
+extension DHUNullableSetExtensions<E> on Set<E>? {
+  /// Converts the set to a different type [R], similar to the original [cast] method,
+  /// but with additional flexibility and error handling.
+  ///
+  /// Unlike the standard [Set.cast], which can throw a [CastError] if an element cannot
+  /// be cast to the specified type [R], [castTo] leverages a custom conversion logic
+  /// which tries various strategies to convert elements.
+  ///
+  /// If a direct cast is not feasible, it attempts element-wise conversion using `toType`.
+  /// This ensures that the conversion happens smoothly without risking a crash.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// Set<dynamic> set = {1, 2, '3'};
+  /// List<int> intList = set.castTo<int>(); // Tries to convert all elements to int.
+  /// ```
+  Set<R> castTo<R>() => ConvertObject.toSet<R>(this);
+}
+
 extension DHUNullableListExtensions<E> on List<E>? {
   /// same behavior as [removeAt] but it is null safe which means
   /// it do nothing when [List] return [isEmptyOrNull] to true.
@@ -80,6 +99,23 @@ extension DHUNullableListExtensions<E> on List<E>? {
   /// it do nothing when [List] return [isEmptyOrNull] to true.
   void tryRemoveWhere(int element) =>
       isEmptyOrNull ? null : this!.removeWhere((element) => false);
+
+  /// Converts the list to a different type [R], similar to the original [cast] method,
+  /// but with additional flexibility and error handling.
+  ///
+  /// Unlike the standard [List.cast], which can throw a [CastError] if an element cannot
+  /// be cast to the specified type [R], [castTo] leverages a custom conversion logic
+  /// which tries various strategies to convert elements.
+  ///
+  /// If a direct cast is not feasible, it attempts element-wise conversion using `toType`.
+  /// This ensures that the conversion happens smoothly without risking a crash.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// List<dynamic> list = [1, 2, '3'];
+  /// List<int> intList = list.castTo<int>(); // Tries to convert all elements to int.
+  /// ```
+  List<R> castTo<R>() => ConvertObject.toList<R>(this);
 }
 
 extension DHUCollectionsExtensionsNS<E> on Iterable<E>? {
@@ -361,6 +397,32 @@ extension DHUCollectionsExtensionsNS<E> on Iterable<E>? {
 }
 
 extension DHUCollectionsExtensions<E> on Iterable<E> {
+  /// Converts the iterable to a [List] of type [R] using the [castTo] method.
+  ///
+  /// This method first converts the iterable to a list, then casts it to the desired
+  /// type [R] using custom conversion logic provided by [castTo]. This ensures flexibility
+  /// and handles potential casting errors gracefully.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// Iterable<dynamic> iterable = [1, '2', 3.0];
+  /// List<int> intList = iterable.toListCasted<int>(); // Tries to convert all elements to int.
+  /// ```
+  List<R> toListCasted<R>() => this.toList().castTo<R>();
+
+  /// Converts the iterable to a [Set] of type [R] using the [castTo] method.
+  ///
+  /// This method first converts the iterable to a set, then casts it to the desired
+  /// type [R] using custom conversion logic provided by [castTo]. This ensures flexibility
+  /// and handles potential casting errors gracefully.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// Iterable<dynamic> iterable = [1, '2', 3.0];
+  /// Set<int> intSet = iterable.toSetCasted<int>(); // Tries to convert all elements to int.
+  /// ```
+  Set<R> toSetCasted<R>() => this.toSet().castTo<R>();
+
   /// Returns this Iterable if it's not `null` and the empty list otherwise.
   Iterable<E> orEmpty() => this;