labeled_list
An implementation of list that accepts an optional label with every element added to the list.
Usage
import 'package:labeled_list/labeled_list.dart';
LabeledList
behaves like any other List
, except its values can
be set and retrieved by an optional label assigned to each element.
final labledList =
LabeledList<String>.of(['a', 'b', 'c'], labels: ['one', 'two', 'three']);
print(labeledList[0]); // a
print(labeledList['one']); // a
labeledList['one'] = 'd';
print(labeledList['one']); // d
Labels can be assigned to elements when a LabeledList
is constructed,
when any new element(s) are added to the list, or with the setLabel
and
setLabelAt
methods.
Note: The underlying list of labels is stored in a strict
UniqueList, as each label
must be null
or unique from every other label.
Constructors
LabeledList
has the same constructors as List
, with one key difference
in the behavior of the of
and from
constructors.
Like the List.of
constructor, the LabeledList.of
constructor constructs
a new list containing the elements of a provided Iterable
, and should be used
to create a new list that doesn't reference the provided Iterable
.
final list = <int>[0, 1, 2];
final labeledList = LabeledList<int>.of(list, labels: ['a', 'b', 'c']);
list.add(4);
print(list); // [0, 1, 2, 3, 4]
print(labeledList); // [0, 1, 2, 3]
The LabeledList.from
constructor behaves the same as the LabeledList.of
constructor if provided an Iterable
that isn't a List
. However, if a List
is provided, the constructed LabeledList
will wrap the provided List
; as such,
any changes made to the provided list will also affect the LabeledList
, as it
references the provided List
.
final list = <int>[0, 1, 2];
final labeledList = LabeledList<int>.from(list, labels: ['a', 'b', 'c']);
list.add(4);
print(list); // [0, 1, 2, 3, 4]
print(labeledList); // [0, 1, 2, 3, 4]
Note: The provided labels
must contain the same number of elements as
the constructed list. null
values should be provided for elements that aren't
labeled.
// Only the element at `1` is labeled.
final labeledList = LabeledList<int>.from([0, 1, 2], labels: [null, 'b', null]);
Adding Elements
The add
and insert
methods take an optional named parameter, label
, to
assign a label to the newly added element.
final labeledList = LabeledList<int>.from([0, 1, 2], labels: ['a', 'b', 'c']);
labeledList.add(3, label: 'd');
print(labeledList['d']); // 3
labeledList.insert(0, 4, label: 'e');
print(labeledList['e']); // 4
The addAll
and insertAll
methods take an optional named parameter, labels
,
to assign labels to the newly added elements.
final labeledList = LabeledList<int>.from([0, 1, 2], labels: ['a', 'b', 'c']);
labeledList.addAll([3, 4, 5], labels: ['d', 'e', 'f']);
labeledList.insertAll(0, [6, 7, 8], labels: ['g', 'h', 'i']);
Retrieving, Setting & Removing Labels
LabeledList
has a handful of methods for interfacing with the labels.
labels
The labels
getter returns a list of every label associated with the
elements in the list. The returned list will contain one value for every
element in the list. Any unlabeled elements will have a label of null
.
final list = LabeledList<int>.of([0, 1, 2], labels: ['a', 'b', 'c']);
print(list.labels); // ['a', 'b', 'c']
Note: The returned list is a copy of the underlying list of labels, as such any changes made to it will not affect the labels in the list.
hasLabel & hasLabelAt
The hasLabel
and hasLabelAt
methods return true
if the list contains
an element associated with the provided label, or if the element at the
provided index has a label, respectively.
final list = LabeledList<int>.of([0, 1, 2], labels: ['a', 'b', null]);
print(list.hasLabel('a')); // true
print(list.hasLabel('c')); // false
print(list.hasLabelAt(0)); // true
print(list.hasLabelAt(2)); // false
indexOfLabel
The indexOfLabel
method returns the index of the element associated with
the provided label.
final list = LabeledList<int>.of([0, 1, 2], labels: ['a', 'b', 'c']);
print(list.indexOfLabel('b')); // 1
getLabel & getLabelAt
The getLabel
and getLabelAt
methods return the label associated with
the provided element, or associated with the element at the provided index,
respectively.
final list = LabeledList<int>.of([0, 1, 2], labels: ['a', 'b', 'c']);
print(list.getLabel(0)); // a
print(list.getLabelAt(0)); // b
setLabel & setLabelAt
The setLabel
and setLabelAt
methods update the label associated
with the provided elemement, or associated with the element at the proivided
index, respectively.
final list = LabeledList<int>.of([5, 6, 7]);
list.setLabel(5, 'a');
print(list['a']); // 5
list.setLabelAt(1, 'b');
print(list['b']); // 6
removeLabelWhere
The removeLabelWhere
method removes the label associated with every element
that passes the provided test. Note: By removing a label, its value is
set to null
in the underlying list of labels.
final list = LabeledList<int>.of([0, 1, 2], labels: ['a', 'b', 'c']);
list.removeLabelWhere((element) => element.isEven);
print(list.labels); // [null, 'b', null]
removeByLabel
The removeByLabel
method removes the element associated with the provided
label from the list.
final list = LabeledList<int>.of([0, 1, 2], labels: ['a', 'b', 'c']);
list.removeByLabel('b');
print(list); // [0, 1]
Libraries
- labeled_list
- An implementation of list that accepts an optional label with every element added to the list.