updated saropa tools

CHANGELOG.md

@@ -1,18 +1,52 @@
 # Change History for Saropa Dart Utils
 
+## 0.0.11 - Rome (Latest)
+
+* 🗑️ Removed deprecated functions in ```StringNullableExtensions```
+
+* 🐛 Fixed ```StringExtensions.removeStart``` to return the input string when the search param is empty
+ ```'Hello, World!'.removeStart(''); // 'Hello, World!'```
+
+* ⚙️ Added constant ```DateConstants.unixEpochDate```
+ ```DateConstants.unixEpochDate; // January 1st, 1970```
+
+* ✨ Added function ```DateConstantExtensions.isUnixEpochDate```
+ ```DateTime.utc(1970).isUnixEpochDate; // true```
+
+* ✨ Added function ```DateConstantExtensions.isUnixEpochDateTime```
+ ```DateTime.utc(1970, 1, 1, 0, 0, 1).isUnixEpochDateTime; // false```
+
+* ✨ Added function ```IntStringExtensions.ordinal```
+ ```101.ordinal(); // 101st```
+
+* ✨ Added function ```StringUtils.getNthLatinLetterLower```
+ ```String? StringUtils.getNthLatinLetterLower(3) // "c"```
+
+* ✨ Added function ```StringUtils.getNthLatinLetterUpper```
+ ```String? StringUtils.getNthLatinLetterUpper(4) // "D"```
+
+* ✨ Added function ```IntUtils.findGreatestCommonDenominator```
+ ```String? IntUtils.findGreatestCommonDenominator(15, 45) // 15```
+
+* ✨ Added function ```IntExtensions.countDigits```
+ ```(-12345).countDigits() // 5```
+
 ## 0.0.10 - Paris
 
-* Change start to be nullable ```String? removeStart(String? start)```
+* Change start to be nullable
+```String? removeStart(String? start)```
 
 ## 0.0.9 - Geneva
 
 * Review of meta data
-* Add trimFirst param to ```StringExtensions.removeStart({bool trimFirst = false,}){...}```
+* Add trimFirst param to
+```StringExtensions.removeStart({bool trimFirst = false,}){...}```
 
 ## 0.0.8 - Nepal
 
 * Review of meta data
-* Add trimFirst param to ```StringExtensions.nullIfEmpty({bool trimFirst = true,}){...}```
+* Add trimFirst param to
+```StringExtensions.nullIfEmpty({bool trimFirst = true,}){...}```
 
 ## 0.0.7 - Jamaica
 

lib/datetime/date_constant_extensions.dart

@@ -0,0 +1,40 @@
+import 'package:saropa_dart_utils/datetime/date_constants.dart';
+
+/// `DateConstantExtensions` is an extension on the `DateTime` class in Dart.
+///  It provides additional properties for performing operations on `DateTime`
+///  instances.
+///
+/// The `isUnixEpochDate` property checks if the year, month, and day of the
+///  `DateTime` instance match those of the Unix epoch date (January 1, 1970).
+///
+/// The `isUnixEpochDateTime` property checks if the `DateTime` instance is
+///  exactly equal to the Unix epoch date and time (00:00:00 UTC, January 1,
+///  1970).
+///
+/// Example usage:
+/// ```dart
+/// DateTime date = DateTime.utc(1970, 1, 1);
+/// bool isEpochDate = date.isUnixEpochDate;  // returns true
+/// bool isEpochDateTime = date.isUnixEpochDateTime;  // returns true
+/// ```
+///
+extension DateConstantExtensions on DateTime {
+  /// Checks if the year, month, and day of the `DateTime` instance
+  /// match those of the Unix epoch date (January 1, 1970).
+  ///
+  /// Returns `true` if the year, month, and day match the Unix epoch date,
+  /// and `false` otherwise.
+  ///
+  bool get isUnixEpochDate =>
+      year == DateConstants.unixEpochDate.year &&
+      month == DateConstants.unixEpochDate.month &&
+      day == DateConstants.unixEpochDate.day;
+
+  /// Checks if the `DateTime` instance is exactly equal to
+  /// the Unix epoch date and time (00:00:00 UTC, January 1, 1970).
+  ///
+  /// Returns `true` if the `DateTime` instance represents the exact
+  /// Unix epoch date and time, and `false` otherwise.
+  ///
+  bool get isUnixEpochDateTime => this == DateConstants.unixEpochDate;
+}

lib/datetime/date_constants.dart

@@ -0,0 +1,23 @@
+/// `DateConstants` is a utility class in Dart that provides static constants
+/// for commonly used dates. This class cannot be instantiated.
+///
+/// The `unixEpochDate` constant in this class represents the Unix epoch,
+/// which is the date and time that Unix systems use as the reference point
+/// for measuring time. The Unix epoch is defined as 00:00:00 Coordinated
+/// Universal Time (UTC), Thursday, 1 January 1970.
+///
+/// Example usage:
+/// ```dart
+/// DateTime epoch = DateConstants.unixEpochDate;
+/// ```
+///
+class DateConstants {
+  /// January 1st, 1970 is known as the Unix epoch. It is the date and
+  /// time that Unix systems use as the reference point for measuring
+  /// time. This date was chosen arbitrarily by early Unix engineers
+  /// because they needed a uniform and convenient date for the start
+  /// of time.
+  ///
+  // NOTE: default month and day == 1
+  static final DateTime unixEpochDate = DateTime.utc(1970);
+}

lib/int/int_extensions.dart

@@ -0,0 +1,55 @@
+/// `IntExtensions` is an extension on the `int` class in Dart. It provides
+/// additional methods for performing operations on integers.
+///
+/// The methods in this extension include, but are not limited to, methods for
+/// counting the number of digits in an integer.
+///
+/// Example usage:
+/// ```dart
+/// int count = 12345.countDigits();  // returns 5
+/// ```
+///
+/// Note: All methods in this extension are null-safe, meaning they will
+///  not throw an exception if the integer on which they are called is null.
+///
+extension IntExtensions on int {
+  /// This function counts the number of digits in an integer.
+  /// It takes an integer as input and returns the number of digits in the
+  ///  integer.
+  ///
+  /// The function handles both positive and negative integers, as well as zero.
+  ///
+  /// It uses the method of repeatedly dividing the number by 10 until it
+  ///  becomes 0,
+  ///
+  /// which is generally more efficient than converting the number to a string
+  ///  and getting its length.
+  ///
+  int countDigits() {
+    // // Count the number of digits in the absolute value of value
+    // return value.abs().toString().length;
+
+    // If the number is 0, return 1
+    if (this == 0) {
+      return 1;
+    }
+
+    // Take the absolute value of the number
+    var number = abs();
+
+    // Initialize a counter for the number of digits
+    var count = 0;
+
+    // Repeat until the number becomes 0
+    while (number != 0) {
+      // Divide the number by 10
+      number ~/= 10;
+
+      // Increment the counter
+      count++;
+    }
+
+    // Return the count
+    return count;
+  }
+}

lib/int/int_string_extensions.dart

@@ -0,0 +1,44 @@
+/// `IntStringExtensions` is an extension on the `int` class in Dart. It
+///  provides additional methods for performing operations on integers.
+///
+/// The `ordinal` method in this extension returns an ordinal number of
+///  `String` type for any integer.
+///
+/// It handles both positive and negative integers, as well as zero.
+///
+/// Example usage:
+/// ```dart
+/// int number = 101;
+/// String ordinalNumber = number.ordinal();  // returns '101st'
+/// ```
+///
+/// Note: All methods in this extension are null-safe, meaning they will not
+///  throw an exception if the integer on which they are called is null.
+///
+extension IntStringExtensions on int {
+  /// Returns an ordinal number of `String` type for any integer
+  ///
+  /// ```dart
+  /// 101.ordinal(); // 101st
+  /// 114.ordinal(); // 101th
+  ///
+  /// 999218.ordinal(); // 999218th
+  /// ```
+  ///
+  /// A [double] typed version can use: value.floor()
+  ///
+  String ordinal() {
+    // all "teens" (12, 13, 14.. 19) are 'th'
+    if (this >= 11 && this <= 19) {
+      return '${this}th';
+    }
+
+    final num onesPlace = this % 10;
+    return switch (onesPlace) {
+      1 => '${this}st',
+      2 => '${this}nd',
+      3 => '${this}rd',
+      _ => '${this}th',
+    };
+  }
+}

lib/int/int_utils.dart

@@ -0,0 +1,65 @@
+/// `IntUtils` is a utility class in Dart that provides static methods
+/// for performing operations on integers. This class cannot be instantiated.
+///
+/// The methods in this class include, but are not limited to, methods for
+/// finding the greatest common denominator (GCD) of two integers using the
+/// Euclidean algorithm.
+///
+/// Example usage:
+/// ```dart
+/// int gcd = IntUtils.findGCD(48, 18);  // returns 6
+/// ```
+///
+/// Note: All methods in this class are null-safe, meaning they will not throw
+/// an exception if the input integers are not within the expected range.
+/// Instead, they will return a reasonable default value (usually null).
+///
+class IntUtils {
+  /// This method finds the greatest common denominator of two integers.
+  /// It uses the Euclidean algorithm, which is based on the principle that the
+  /// greatest common denominator of two numbers does not change if the larger
+  /// number is replaced by its difference with the smaller number.
+  ///
+  /// [depth] is used to track the recursion depth, and [maxDepth] is used to
+  /// prevent the recursion from going too deep.
+  ///
+  /// Both [a] and [b] must be non-negative.
+  ///
+  static int? findGreatestCommonDenominator(
+    int a,
+    int b, {
+    int depth = 0,
+    int maxDepth = 500,
+  }) {
+    // Both numbers must be non-negative.
+    if (a < 0 || b < 0) {
+      return null;
+    }
+
+    // If the recursion depth exceeds the maximum depth, return -1.
+    if (depth > maxDepth) {
+      return null;
+    }
+
+    // If [a] and [b] are both zero, return null as GCD is undefined.
+    if (a == 0 && b == 0) {
+      return null;
+    }
+
+    // If [b] is 0, then [a] is the greatest common denominator.
+    if (b == 0) {
+      return a;
+    }
+
+    /*** NOTE: RECURSION ***/
+
+    // Otherwise, recursively call this method with [b] and the remainder of
+    // [a] divided by [b].
+    return findGreatestCommonDenominator(
+      b,
+      a % b,
+      depth: depth + 1,
+      maxDepth: maxDepth,
+    );
+  }
+}