arcane/arcane_helper_utils
1
0
Fork 0
mirror of https://github.com/hanskokx/arcane_helper_utils.git synced 2026-05-14 02:19:09 +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
- **Ticker Utility**: A utility class that facilitates time-based actions,
perfect for animations or any timing-related operations.
- **JSON Converter**: Simplifies the process of converting JSON data into
Dart objects.
- **DateTime Extensions**: Adds additional functionality to the `DateTime`
class, making it easier to format dates and calculate differences.
- **String Extensions**: Enhances the `String` class by adding new methods for
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.
- **Ticker Utility**: A utility class that facilitates time-based actions, perfect for animations or any timing-related operations.
- **JSON Converter**: Simplifies the process of converting JSON data into Dart objects.
- **DateTime Extensions**: Adds additional functionality to the `DateTime` class, making it easier to format dates and calculate differences.
- **String Extensions**: Enhances the `String` class by adding new methods for 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.
- **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.
## Getting Started
To use this package in your Dart project, add it to your project's
`pubspec.yaml` file:
To use this package in your Dart project, add it to your project's `pubspec.yaml` file:
```yaml
dependencies:
@@ -40,8 +32,7 @@ import 'package:arcane_helper_utils/arcane_helper_utils.dart';
## Usage Examples
Here are some examples of how to use the utilities and extensions provided by
this package:
Here are some examples of how to use the utilities and extensions provided by this package:
### Ticker
@@ -61,17 +52,13 @@ await for (final int ticksRemaining in ticker) {
### JSON Conversion
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.
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.
The available conversions are:
- `String?` to `int?`
- `String?` to `double?`
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?`:
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?`:
```json
{
@@ -99,9 +86,7 @@ abstract class MyFreezedClass with _$MyFreezedClass {
### DateTime Extensions
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.
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.
These are broken down into the following categories:
@@ -109,13 +94,13 @@ These are broken down into the following categories:
- Comparison operations
- Period information operations
- "Yesterday" and "tomorrow" getters
- Leap year calculations
#### Start and End of Period Calculations
The following operations are now available on a `DateTime` object:
- `startOfHour`: Returns a new `DateTime` object where the time stamp is set to
the beginning of the given hour.
- `startOfHour`: Returns a new `DateTime` object where the time stamp is set to the beginning of the given hour.
```dart
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
```
- `endOfHour`: Returns a new `DateTime` object where the time stamp is set to
the end of the given hour.
- `endOfHour`: Returns a new `DateTime` object where the time stamp is set to the end of the given hour.
```dart
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
```
- `startOfDay`: Returns a new `DateTime` object where the time stamp is set to
the beginning of the day.
- `startOfDay`: Returns a new `DateTime` object where the time stamp is set to the beginning of the day.
```dart
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
```
- `endOfDay`: Returns a new `DateTime` object where the time stamp is set to the
end of the day.
- `endOfDay`: Returns a new `DateTime` object where the time stamp is set to the end of the day.
```dart
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
```
- `startOfWeek`: Returns a new `DateTime` object where the time stamp is set to
the beginning of the week (Monday).
- `startOfWeek`: Returns a new `DateTime` object where the time stamp is set to the beginning of the week (Monday).
```dart
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
```
- `endOfWeek`: Returns a new `DateTime` object where the time stamp is set to
the end of the week (Sunday).
- `endOfWeek`: Returns a new `DateTime` object where the time stamp is set to the end of the week (Sunday).
```dart
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
```
- `startOfMonth`: Returns a new `DateTime` object where the time stamp is set to
the beginning of the month.
- `startOfMonth`: Returns a new `DateTime` object where the time stamp is set to the beginning of the month.
```dart
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
```
- `endOfMonth`: Returns a new `DateTime` object where the time stamp is set to
the end of the month.
- `endOfMonth`: Returns a new `DateTime` object where the time stamp is set to the end of the month.
```dart
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
```
- `startOfYear`: Returns a new `DateTime` object where the time stamp is set to
the beginning of the year.
- `startOfYear`: Returns a new `DateTime` object where the time stamp is set to the beginning of the year.
```dart
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
```
- `endOfYear`: Returns a new `DateTime` object where the time stamp is set to
the end of the year.
- `endOfYear`: Returns a new `DateTime` object where the time stamp is set to the end of the year.
```dart
final DateTime dateTime = DateTime(2023, 9, 10);
@@ -206,16 +182,14 @@ The following operations are now available on a `DateTime` object:
#### Comparison Operations
- `isToday`: Returns `true` if the provided `DateTime` is today, otherwise
returns `false`.
- `isToday`: Returns `true` if the provided `DateTime` is today, otherwise returns `false`.
```dart
final DateTime today = DateTime(2024, 9, 10);
final bool notToday = DateTime(2001, 12, 31).isToday; // false
```
- `isSameDayAs`: Compares two `DateTime` objects and returns `true` if they
represent the same day.
- `isSameDayAs`: Compares two `DateTime` objects and returns `true` if they represent the same day.
```dart
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
```
- `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.
- `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.
```dart
final DateTime today = DateTime(2024, 9, 10); // Tuesday
@@ -260,8 +233,7 @@ The following operations are now available on a `DateTime` object:
#### Leap Years
- `isLeapYear`: returns a `bool` corresponding to whether a given year is a leap
year. This can also be used directly on an `int`.
- `isLeapYear`: returns a `bool` corresponding to whether a given year is a leap year. This can also be used directly on an `int`.
```dart
print(DateTime(2024).isLeapYear); // true
@@ -272,8 +244,7 @@ The following operations are now available on a `DateTime` object:
### JWT Parsing
These extensions enhance the `String` class with JWT-specific functionalities,
making it easier to handle JSON Web Tokens directly as `String` objects.
These extensions enhance the `String` class with JWT-specific functionalities, making it easier to handle JSON Web Tokens directly as `String` objects.
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
The following utilities have been added to enhance working with `String`
objects:
The following utilities have been added to enhance working with `String` objects:
- `isNullOrEmpty`: Returns `true` if a `String?` is either null or consists of
only whitespace.
- `isNullOrEmpty`: Returns `true` if a `String?` is either null or consists of only whitespace.
```dart
const String? nullString = null;
@@ -338,8 +307,7 @@ objects:
print(nonEmptyString.isNullOrEmpty) // false
```
- `isNotNullOrEmpty`: Returns `true` if a `String?` is neither null nor consists
of only whitespace.
- `isNotNullOrEmpty`: Returns `true` if a `String?` is neither null nor consists of only whitespace.
```dart
const String? nullString = null;
@@ -351,8 +319,7 @@ objects:
print(nonEmptyString.isNotNullOrEmpty) // true
```
- `splitByLength(int length)`: Splits a `String` into a `List<String>` where
each value is of the maximum length provided.
- `splitByLength(int length)`: Splits a `String` into a `List<String>` where each value is of the maximum length provided.
```dart
const String text = "DartLang";
@@ -380,16 +347,13 @@ objects:
String spaced = text.spacePascalCase; // "Arcane Helper Utils"
```
Additionally, the `CommonString` class provides a quick shortcut to common
strings, such as punctuation marks that are otherwise cumbersome to find or type.
Additionally, the `CommonString` class provides a quick shortcut to common strings, such as punctuation marks that are otherwise cumbersome to find or type.
### List Extensions
The following extensions have been added to the `List` object:
- `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.
- `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.
```dart
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));
```
### 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
Contributions are welcome! Feel free to fork the repository and submit pull
requests.
Contributions are welcome! Feel free to fork the repository and submit pull requests.