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(['zero', 'one', 'two'], labels: ['a', 'b', 'c']);

print(labeledList[0]); // zero
print(labeledList['a']); // zero

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]