unique_list
An implementation of List that enforces all elements be unique.
Usage
import 'package:unique_list/unique_list.dart';
UniqueList is an implementation of List that doesn't allow the same element
to occur in the List more than once (much like a Set.) Elements will be
considered identical if comparing them with the == operator returns true.
The UniqueList class implements List, as such it has all of the same methods and parameters of a List, can be used interchangeably with a List, and be provided to any parameter that enforces a List.
The default constructor is identical to Lists', accepting an optional length
parameter. If length is provided the UniqueList will be a fixed-length list.
/// Create an empty [UniqueList].
final list = UniqueList();
/// Create an empty [UniqueList] of [int]s.
final integers = UniqueList<int>();
/// Create a fixed-length [UniqueList] of [int]s.
final fiveIntegers = UniqueList<int>(5);
By default, UniqueList doesn't allows for multiple instances of null to be
contained within the list, unless creating a fixed-lenght list. To create a
UniqueList that allows for multiple instances of null to occur, the nullable
parameter can be set to true.
/// Create an empty [UniqueList] that allows multiple instances of `null`.
final list = UniqueList.empty(nullable: true);
Strict Lists
By default, UniqueList behaves like a Set, when an element that already exists in the list is added to it, the list will be left as it was. The UniqueList.strict constructor can be used to create a list that will throw a DuplicateValueError instead.
final list = UniqueList<int>();
list.addAll([0, 1, 2]);
list.add(0);
print(list); // [0, 1, 2]
final strictList = UniqueList<int>.strict();
strictList.addAll([0, 1, 2]);
strictList.add(0); // This will throw a [DuplicateValueError].
Factory Constructors
UniqueList has all of the same factory constructors as a regular List, with
the exception of List.filled, as the values created by filled would not be
unique.
Each of UniqueList's factory constructors have a strict and a nullable
parameter, and most have a growable parameter like List.
UniqueList.from
/// Create a new [UniqueList] list containing all elements from another list.
final list = UniqueList<int>.from([0, 1, 2]);
final strict = UniqueList<int>.from([0, 1, 2], strict: true);
final nullable = UniqueList<int>.from([0, 1, 2], nullable: true);
UniqueList.of
/// Create a new [UniqueList] list from an iterable.
final list = UniqueList<int>.of([0, 1, 2]);
final strict = UniqueList<int>.of([0, 1, 2], strict: true);
final nullable = UniqueList<int>.of([0, 1, 2], nullable: true);
UniqueList.generate
/// Generate a new [UniqueList] using a generator.
final list = UniqueList<int>.generate(5, (index) => index); // [0, 1, 2, 3, 4]
final strict = UniqueList<int>.generate(5, (index) => index, strict: true);
final nullable = UniqueList<int>.generate(5, (index) => index, nullable: true);
UniqueList.unmodifiable
UniqueList.unmodifiable is the only standard factory constructor without a strict
parameter, as it isn't necessary if the list can't be modified.
/// Create an unmodifiable [UniqueList] from an iterable.
final list = UniqueList<int>.unmodifiable([0, 1, 2]);
final nullable = UniqueList<int>.unmodifiable([0, 1, 2], nullable: true);
Constructor Errors
Attempting to construct a strict list that contains multiple instances of the same element, will throw a DuplicateValuesError, as opposed to the DuplicateValueError thrown when attempting to add a duplicate element to a list.
A DuplicateValuesError will also be thrown if attempting to construct a fixed-length list that contains multiple instances of the same element.
Adding and Inserting Elements
Adding and inserting values into a non-strict UniqueList have different behavior when a duplicate element is provided. Both will throw a DuplicateValueError if adding or inserting duplicate elements into a strict list.
Add and AddAll
When adding elements into a list with the add or addAll method, any duplicate
values will be ignored.
final list = UniqueList<int>.from([0, 1, 2]);
print(list); // [0, 1, 2]
list.add(3);
print(list); // [0, 1, 2, 3]
list.add(2);
print(list); // [0, 1, 2, 3]
list.addAll([0, 1, 4, 5]);
print(list); // [0, 1, 2, 3, 4, 5]
Insert and InsertAll
When inserting one or more elements into the list with the insert or insertAll
method, any existing instances of any of the elements being inserted will be removed,
shifting the indexes of all elements occuring after the one(s) removed down.
final list = UniqueList<int>.from([0, 1, 2]);
print(list); // [0, 1, 2]
list.insert(0, 3);
print(list); // [3, 0, 1, 2]
list.insert(3, 3);
print(list); // [0, 1, 2, 3]
list.insertAll(3, [0, 1, 2]);
print(list); // [3, 0, 1, 2]
Setting Values
When setting values with the setAll, setRange, first, last, or the []=
operator a DuplicateValueError will always be thrown, regardless of whether the
list is strict or not, unless the resulting list does not contain any duplicate
values once all values have been set.
final list = UniqueList<int>.from([0, 1, 2]);
print(list); // [0, 1, 2]
list.setAll(0, [0, 1, 2]); // Throws a [DuplicateValueError].
list.setRange(1, 2, [3, 4]);
print(list); // [0, 3, 4]
list.setRange(0, 1, [2, 3]); // Throws a [DuplicateValueError].
Note: In order to comply with List, the fillRange method is provided, but
will always throw a DuplicateValueError unless the value being filled is null
in a nullable list, or if only a single element is being set.
The ToUniqueList Extension Method
As many of List's methods return an Iterable, they're often cast back to a
List using Iterable's toList method. To follow the same pattern, this package
extends Iterable with the toUniqueList method.
Like toList, the toUniqueList method contains a growable parameter, in
addition to the nullable and strict parameters, which by default are true
and false respectively.
var list = UniqueList<int>.from([0, 1, 2, 3, 4]);
final reversed = list.reversed.toUniqueList();
print(reversed); // [4, 3, 2, 1, 0]