unique_list

Description:

unique list

unique_list #

An implementation of [List] that enforces all elements be unique.
Usage #
import 'package:unique_list/unique_list.dart';
copied to clipboard
[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 [List]s', 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);
copied to clipboard
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);
copied to clipboard
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].
copied to clipboard
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);
copied to clipboard
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);
copied to clipboard
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);
copied to clipboard
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);
copied to clipboard
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]
copied to clipboard
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]
copied to clipboard
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].
copied to clipboard
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]
copied to clipboard

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter