A Flutter - Dart package that provides a list with unique elements based on a custom uniqueness condition.
MIT License
XUniqueList
is a utility package that ensures uniqueness in your lists based on a custom condition
you define. It's perfect for managing collections of objects that must adhere to specific uniqueness
rules.
Android | IOS | Web | MacOS | Linux | Windows |
---|---|---|---|---|---|
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
To start using XUniqueList
, you need to add the following dependency to your pubspec.yaml
file:
dependencies:
x_unique_list: ^1.0.5
flutter pub get
dart pub get
Here’s an example of using XUniqueList
with a custom uniqueCondition
based on the id
field of
a User
class:
import 'package:x_unique_list/x_unique_list.dart';
class User {
final int id;
final String name;
User(this.id, this.name);
@override
String toString() => 'User(id: $id, name: $name)';
// Override equality operator to compare both id and name
@override
bool operator ==(Object other) =>
identical(this, other) ||
(other is User && id == other.id && name == other.name);
@override
int get hashCode => Object.hash(id, name);
}
void main() {
// Define a unique condition (in this case, users are unique by their ID)
final uniqueUsers = XUniqueList<User>((user) => user.id);
// Add users
uniqueUsers.add(User(1, 'Ahmad'));
uniqueUsers.add(User(2, 'Nour'));
// Attempt to add a duplicate user (will not be added)
uniqueUsers.add(User(1, 'Ahmad')); // This won't be added as ID 1 already exists
// Retrieve unmodifiable list of users
print(uniqueUsers.items); // [User(id: 1, name: Ahmad), User(id: 2, name: Nour)]
// Remove a user - ⚠️ NOTE: This may not work as expected
// ⚠️ Won't work unless you override `==` and `hashCode` for User
uniqueUsers.remove(User(2, 'Nour'));
// Explanation:
// The `remove` method uses the `==` operator to check if the items match.
// By default, Dart compares objects by their memory reference, not by the fields inside the object.
// To make this work, you need to either manually override the `==` operator and `hashCode`
// for your model (as shown above), or use third-party libraries like `equatable`, `freezed`, etc.
// As an alternative, you can use `removeOneWhere` to remove an item by a condition
uniqueUsers.removeOneWhere((user) => user.id == 2); // Works even without `==` override
// Check if list contains a user
// ⚠️ Important Note on `contains` Method
//
// The `contains` method in `XUniqueList` relies on the `uniqueCondition` you define.
// In the example above, the `uniqueCondition` is based on the `id` field of the `User` class.
//
// This means that when you check for the existence of an item using `contains`,
// it only considers the value provided by the `uniqueCondition` function, not the entire object.
//
// For instance:
bool exists = uniqueUsers.contains(User(1, 'Ahmad'));
print(exists); // true
// Even though the name 'Ahmad' is different from any existing user, the contains method returns true
// because the id field (which is the unique condition) matches the ID of an existing user (ID = 1).
// To check for existence or remove items based on different criteria (such as the name),
// you can use the removeOneWhere method, which allows for more complex condition-based logic.
}
The XUniqueList
class provides various methods for managing unique lists. Here is a comprehensive
overview of all the methods available:
List<T> get items;
List<T> get data;
T operator [](int index);
bool add(T item);
int addAll(List<T> newItems);
bool insert(int index, T item);
int insertAll(int index, Iterable<T> newItems);
bool remove(T item);
bool removeOneWhere(bool Function(T) test);
void removeWhere(bool Function(T e) test);
bool replaceOne(T newItem);
bool replaceOneWhere(T newItem, bool Function(T) test);
void sort([int Function(T a, T b)? compare]);
List<T> where(bool Function(T) test);
T? firstWhere(bool Function(T) test);
int indexWhere(bool Function(T) test);
int indexOf(T item);
bool contains(T item);
int get length;
bool get isEmpty;
bool get isNotEmpty;
void clear();
In future updates, we plan to introduce additional helper methods to further enhance the
functionality of the XUniqueList
class.
This package is licensed under the MIT License. See the LICENSE file for details.