arcane/arcane_helper_utils
1
0
Fork 0
mirror of https://github.com/hanskokx/arcane_helper_utils.git synced 2026-05-14 10:29:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Hans Kokx
2025-05-16 14:58:50 +02:00
parent f4b5c252d7
commit a3b2dc5c26
1 changed files with 336 additions and 326 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+82 -72
View File
@@ -7,25 +7,17 @@ providing utility functions and extensions that simplify common tasks.
## Features ## Features
- **Ticker Utility**: A utility class that facilitates time-based actions, - **Ticker Utility**: A utility class that facilitates time-based actions, perfect for animations or any timing-related operations.
perfect for animations or any timing-related operations. - **JSON Converter**: Simplifies the process of converting JSON data into Dart objects.
- **JSON Converter**: Simplifies the process of converting JSON data into - **DateTime Extensions**: Adds additional functionality to the `DateTime` class, making it easier to format dates and calculate differences.
Dart objects. - **String Extensions**: Enhances the `String` class by adding new methods for common transformations and checks.
- **DateTime Extensions**: Adds additional functionality to the `DateTime` - **JWT Utilities**: Provides getters to parse a JWT token from a `String`, then get common properties from it.
class, making it easier to format dates and calculate differences. - **List Extensions**: Adds a new `unique` operator for filtering `List` items, as well as getters for `isNullOrEmpty`, `isEmptyOrNull`, `isNotNullOrEmpty`, and `isNotEmptyOrNull`. Furthermore, an `equals` extension has been introduced which can be used to compare two lists.
- **String Extensions**: Enhances the `String` class by adding new methods for - **FixedSizeList**: Provides a list of a predictable size, which drops the first value when additional values are added which would otherwise cause the list to exceed its capacity.
common transformations and checks.
- **JWT Utilities**: Provides getters to parse a JWT token from a `String`, then
get common properties from it.
- **List Extensions**: Adds a new `unique` operator for filtering `List` items,
as well as getters for `isNullOrEmpty`, `isEmptyOrNull`, `isNotNullOrEmpty`,
and `isNotEmptyOrNull`. Furthermore, an `equals` extension has been introduced
which can be used to compare two lists.
## Getting Started ## Getting Started
To use this package in your Dart project, add it to your project's To use this package in your Dart project, add it to your project's `pubspec.yaml` file:
`pubspec.yaml` file:
```yaml ```yaml
dependencies: dependencies:
@@ -40,8 +32,7 @@ import 'package:arcane_helper_utils/arcane_helper_utils.dart';
## Usage Examples ## Usage Examples
Here are some examples of how to use the utilities and extensions provided by Here are some examples of how to use the utilities and extensions provided by this package:
this package:
### Ticker ### Ticker
@@ -61,17 +52,13 @@ await for (final int ticksRemaining in ticker) {
### JSON Conversion ### JSON Conversion
These helper methods are used in conjunction with the Freezed package to These helper methods are used in conjunction with the Freezed package to annotate fields that need to be converted from one data type to another.
annotate fields that need to be converted from one data type to another.
The available conversions are: The available conversions are:
- `String?` to `int?` - `String?` to `int?`
- `String?` to `double?` - `String?` to `double?`
Provided the following JSON output, the `valueIsMaybeNull` field will be Provided the following JSON output, the `valueIsMaybeNull` field will be converted from an empty `String` to `null`, the `valueIsDouble` field will be converted from a `String?` to a `double?`, and the `valueIsInt` field will be converted from a `String?` to an `int?`:
converted from an empty `String` to `null`, the `valueIsDouble` field will
be converted from a `String?` to a `double?`, and the `valueIsInt` field will be
converted from a `String?` to an `int?`:
```json ```json
{ {
@@ -99,9 +86,7 @@ abstract class MyFreezedClass with _$MyFreezedClass {
### DateTime Extensions ### DateTime Extensions
These extensions add helpful methods to the `DateTime` class, making it easier These extensions add helpful methods to the `DateTime` class, making it easier to handle common date and time operations such as formatting, comparisons, and calculations.
to handle common date and time operations such as formatting, comparisons, and
calculations.
These are broken down into the following categories: These are broken down into the following categories:
@@ -109,13 +94,13 @@ These are broken down into the following categories:
- Comparison operations - Comparison operations
- Period information operations - Period information operations
- "Yesterday" and "tomorrow" getters - "Yesterday" and "tomorrow" getters
- Leap year calculations
#### Start and End of Period Calculations #### Start and End of Period Calculations
The following operations are now available on a `DateTime` object: The following operations are now available on a `DateTime` object:
- `startOfHour`: Returns a new `DateTime` object where the time stamp is set to - `startOfHour`: Returns a new `DateTime` object where the time stamp is set to the beginning of the given hour.
the beginning of the given hour.
```dart ```dart
final DateTime dateTime = DateTime(2019, 1, 1, 13, 45); final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
@@ -123,8 +108,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.startOfHour); // 2019-01-01T13:00:00.0 print(dateTime.startOfHour); // 2019-01-01T13:00:00.0
``` ```
- `endOfHour`: Returns a new `DateTime` object where the time stamp is set to - `endOfHour`: Returns a new `DateTime` object where the time stamp is set to the end of the given hour.
the end of the given hour.
```dart ```dart
final DateTime dateTime = DateTime(2019, 1, 1, 13, 45); final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
@@ -132,8 +116,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.endOfHour); // 2019-01-01T13:59:59.999 print(dateTime.endOfHour); // 2019-01-01T13:59:59.999
``` ```
- `startOfDay`: Returns a new `DateTime` object where the time stamp is set to - `startOfDay`: Returns a new `DateTime` object where the time stamp is set to the beginning of the day.
the beginning of the day.
```dart ```dart
final DateTime dateTime = DateTime(2019, 1, 1, 13, 45); final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
@@ -141,8 +124,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.startOfDay); // 2019-01-01T00:00:00.0 print(dateTime.startOfDay); // 2019-01-01T00:00:00.0
``` ```
- `endOfDay`: Returns a new `DateTime` object where the time stamp is set to the - `endOfDay`: Returns a new `DateTime` object where the time stamp is set to the end of the day.
end of the day.
```dart ```dart
final DateTime dateTime = DateTime(2019, 1, 1, 13, 45); final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
@@ -150,8 +132,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.endOfDay); // 2019-01-01T23:59:59.9 print(dateTime.endOfDay); // 2019-01-01T23:59:59.9
``` ```
- `startOfWeek`: Returns a new `DateTime` object where the time stamp is set to - `startOfWeek`: Returns a new `DateTime` object where the time stamp is set to the beginning of the week (Monday).
the beginning of the week (Monday).
```dart ```dart
final DateTime dateTime = DateTime(2023, 9, 10); final DateTime dateTime = DateTime(2023, 9, 10);
@@ -159,8 +140,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.startOfWeek); // 2023-09-04 print(dateTime.startOfWeek); // 2023-09-04
``` ```
- `endOfWeek`: Returns a new `DateTime` object where the time stamp is set to - `endOfWeek`: Returns a new `DateTime` object where the time stamp is set to the end of the week (Sunday).
the end of the week (Sunday).
```dart ```dart
final DateTime dateTime = DateTime(2023, 9, 10); final DateTime dateTime = DateTime(2023, 9, 10);
@@ -168,8 +148,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.endOfWeek); // 2023-09-17T23:59:59.999999 print(dateTime.endOfWeek); // 2023-09-17T23:59:59.999999
``` ```
- `startOfMonth`: Returns a new `DateTime` object where the time stamp is set to - `startOfMonth`: Returns a new `DateTime` object where the time stamp is set to the beginning of the month.
the beginning of the month.
```dart ```dart
final DateTime dateTime = DateTime(2023, 9, 10); final DateTime dateTime = DateTime(2023, 9, 10);
@@ -177,8 +156,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.startOfMonth); // 2023-09-01T00:00:00.0 print(dateTime.startOfMonth); // 2023-09-01T00:00:00.0
``` ```
- `endOfMonth`: Returns a new `DateTime` object where the time stamp is set to - `endOfMonth`: Returns a new `DateTime` object where the time stamp is set to the end of the month.
the end of the month.
```dart ```dart
final DateTime dateTime = DateTime(2023, 9, 10); final DateTime dateTime = DateTime(2023, 9, 10);
@@ -186,8 +164,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.endOfMonth); // 2023-09-30T23:59:59.999999 print(dateTime.endOfMonth); // 2023-09-30T23:59:59.999999
``` ```
- `startOfYear`: Returns a new `DateTime` object where the time stamp is set to - `startOfYear`: Returns a new `DateTime` object where the time stamp is set to the beginning of the year.
the beginning of the year.
```dart ```dart
final DateTime dateTime = DateTime(2023, 9, 10); final DateTime dateTime = DateTime(2023, 9, 10);
@@ -195,8 +172,7 @@ The following operations are now available on a `DateTime` object:
print(dateTime.startOfYear); // 2023-01-01T00:00:00.0 print(dateTime.startOfYear); // 2023-01-01T00:00:00.0
``` ```
- `endOfYear`: Returns a new `DateTime` object where the time stamp is set to - `endOfYear`: Returns a new `DateTime` object where the time stamp is set to the end of the year.
the end of the year.
```dart ```dart
final DateTime dateTime = DateTime(2023, 9, 10); final DateTime dateTime = DateTime(2023, 9, 10);
@@ -206,16 +182,14 @@ The following operations are now available on a `DateTime` object:
#### Comparison Operations #### Comparison Operations
- `isToday`: Returns `true` if the provided `DateTime` is today, otherwise - `isToday`: Returns `true` if the provided `DateTime` is today, otherwise returns `false`.
returns `false`.
```dart ```dart
final DateTime today = DateTime(2024, 9, 10); final DateTime today = DateTime(2024, 9, 10);
final bool notToday = DateTime(2001, 12, 31).isToday; // false final bool notToday = DateTime(2001, 12, 31).isToday; // false
``` ```
- `isSameDayAs`: Compares two `DateTime` objects and returns `true` if they - `isSameDayAs`: Compares two `DateTime` objects and returns `true` if they represent the same day.
represent the same day.
```dart ```dart
final DateTime first = DateTime(2001, 1, 1); final DateTime first = DateTime(2001, 1, 1);
@@ -234,8 +208,7 @@ The following operations are now available on a `DateTime` object:
final int daysInMonth = DateTime(2024, 9).daysInMonth; // 30 final int daysInMonth = DateTime(2024, 9).daysInMonth; // 30
``` ```
- `firstDayOfWeek`: Returns a new `DateTime` object where the time stamp is set - `firstDayOfWeek`: Returns a new `DateTime` object where the time stamp is set to the beginning of the first day (Sunday) of the original `DateTime`'s week.
to the beginning of the first day (Sunday) of the original `DateTime`'s week.
```dart ```dart
final DateTime today = DateTime(2024, 9, 10); // Tuesday final DateTime today = DateTime(2024, 9, 10); // Tuesday
@@ -260,8 +233,7 @@ The following operations are now available on a `DateTime` object:
#### Leap Years #### Leap Years
- `isLeapYear`: returns a `bool` corresponding to whether a given year is a leap - `isLeapYear`: returns a `bool` corresponding to whether a given year is a leap year. This can also be used directly on an `int`.
year. This can also be used directly on an `int`.
```dart ```dart
print(DateTime(2024).isLeapYear); // true print(DateTime(2024).isLeapYear); // true
@@ -272,8 +244,7 @@ The following operations are now available on a `DateTime` object:
### JWT Parsing ### JWT Parsing
These extensions enhance the `String` class with JWT-specific functionalities, These extensions enhance the `String` class with JWT-specific functionalities, making it easier to handle JSON Web Tokens directly as `String` objects.
making it easier to handle JSON Web Tokens directly as `String` objects.
Here are some examples of how these methods can be utilized: Here are some examples of how these methods can be utilized:
@@ -322,11 +293,9 @@ Here are some examples of how these methods can be utilized:
### String Utilities ### String Utilities
The following utilities have been added to enhance working with `String` The following utilities have been added to enhance working with `String` objects:
objects:
- `isNullOrEmpty`: Returns `true` if a `String?` is either null or consists of - `isNullOrEmpty`: Returns `true` if a `String?` is either null or consists of only whitespace.
only whitespace.
```dart ```dart
const String? nullString = null; const String? nullString = null;
@@ -338,8 +307,7 @@ objects:
print(nonEmptyString.isNullOrEmpty) // false print(nonEmptyString.isNullOrEmpty) // false
``` ```
- `isNotNullOrEmpty`: Returns `true` if a `String?` is neither null nor consists - `isNotNullOrEmpty`: Returns `true` if a `String?` is neither null nor consists of only whitespace.
of only whitespace.
```dart ```dart
const String? nullString = null; const String? nullString = null;
@@ -351,8 +319,7 @@ objects:
print(nonEmptyString.isNotNullOrEmpty) // true print(nonEmptyString.isNotNullOrEmpty) // true
``` ```
- `splitByLength(int length)`: Splits a `String` into a `List<String>` where - `splitByLength(int length)`: Splits a `String` into a `List<String>` where each value is of the maximum length provided.
each value is of the maximum length provided.
```dart ```dart
const String text = "DartLang"; const String text = "DartLang";
@@ -380,16 +347,13 @@ objects:
String spaced = text.spacePascalCase; // "Arcane Helper Utils" String spaced = text.spacePascalCase; // "Arcane Helper Utils"
``` ```
Additionally, the `CommonString` class provides a quick shortcut to common Additionally, the `CommonString` class provides a quick shortcut to common strings, such as punctuation marks that are otherwise cumbersome to find or type.
strings, such as punctuation marks that are otherwise cumbersome to find or type.
### List Extensions ### List Extensions
The following extensions have been added to the `List` object: The following extensions have been added to the `List` object:
- `unique([Id Function(E element)? id, bool inplace = true])`: Filters a list - `unique([Id Function(E element)? id, bool inplace = true])`: Filters a list by a given element, returning only non-duplicate values. Can return either a new `List` or filter the existing list by specifying the `inplace` option.
by a given element, returning only non-duplicate values. Can return either a
new `List` or filter the existing list by specifying the `inplace` option.
```dart ```dart
const List<int> list = [1, 2, 2, 3, 4, 4]; const List<int> list = [1, 2, 2, 3, 4, 4];
@@ -461,7 +425,53 @@ The following extensions have been added to the `List` object:
print(list8.equals(list9, ignoreSorting: false)); print(list8.equals(list9, ignoreSorting: false));
``` ```
### Fixed size list
The `FixedSizeList` operates much like a traditional `List` with one exception: the length of the list is defined upon creation and adding new items to the list which would otherwise cause the length of the list to exceed the list's capacity will cause the first item(s) to be removed from the list.
Here's an example: Say you want to keep a list of the last 3 log messages. You can create a `FixedSizeList` to push these log messages into:
```dart
// Create a FixedSizeList with a capacity of 3 strings.
final recentLogs = FixedSizeList(3);
// Output: Initial recentLogs: []
print("Initial recentLogs: ${recentLogs.items}");
// Add some log messages.
recentLogs.add("Request received at 10:00 AM");
print("recentLogs after first add: ${recentLogs.items}");
// Output: recentLogs after first add: [Request received at 10:00 AM]
recentLogs.add("Processing request...");
print("recentLogs after second add: ${recentLogs.items}");
// Output: recentLogs after second add: [Request received at 10:00 AM, Processing request...]
recentLogs.add("Request completed at 10:05 AM");
print("recentLogs after third add: ${recentLogs.items}");
// Output: recentLogs after third add: [Request received at 10:00 AM, Processing request..., Request completed at 10:05 AM]
// Add one more log message, which will cause the oldest one to be removed.
recentLogs.add("Sending response...");
print("recentLogs after fourth add: ${recentLogs.items}");
// Output: recentLogs after fourth add: [Processing request..., Request completed at 10:05 AM, Sending response...]
```
A `FixedSizeList` can be created with a capacity then filled up later (as in the previous example), or a value can be passed in alongside the capacity. The value being passed in should not exceed the length of the given capacity.
```dart
final numbers = FixedSizeList.from([1, 2, 3]); // The list is set to a capacity of 3 (the length of the input)
final moreNumbers = FixedSizeList(3, value: [1, 2, 3]);
final throwsException = FixedSizeList(3, value: [1, 2, 3, 4]); // Throws an exception because [value] exceeds the given capacity.
```
Other `List` factories are supported when creating a `FixedSizeList`, including:
- `filled`
- `empty`
- `from`
- `of`
- `generate`
## Contributing ## Contributing
Contributions are welcome! Feel free to fork the repository and submit pull Contributions are welcome! Feel free to fork the repository and submit pull requests.
requests.