built_collection 4.3.2

  • Readme
  • Changelog
  • Example
  • Installing
  • 99

Built Collections for Dart #

Build Status

Introduction #

Built Collections are immutable collections using the builder pattern.

Each of the core SDK collections is split in two: a mutable builder class and an immutable "built" class. Builders are for computation, "built" classes are for safely sharing with no need to copy defensively.

Immutable collections work particularly well with immutable values. See built_value.

You can read more about built_collection on medium.

Design #

Built Collections:

  • are immutable, if the elements/keys/values used are immutable;
  • are comparable;
  • are hashable;
  • reject nulls;
  • require generic type parameters;
  • reject wrong-type elements;
  • use copy-on-write to avoid copying unnecessarily.

See below for details on each of these points.

A note about strong mode #

Please note that from version 1.1.0 built_collection must be used in conjunction with strong mode to get all the type guarantees. That is, your project must have no warnings or errors when analyzed with the strong mode analyzer. This allows some runtime checks to be skipped because the equivalent check can be done statically.

A project can benefit greatly from using Built Collections throughout. Methods that will not mutate a collection can accept the "built" version, making it clear that no mutation will happen and completely avoiding the need for defensive copying.

For code that is public to other projects or teams not using Built Collections, prefer to accept Iterable where possible. That way your code is compatible with SDK collections, Built Collections and any other collection implementation that builds on Iterable.

It's okay to accept List, Set or Map if needed. Built Collections provide efficient conversion to their SDK counterparts via BuiltList.toList, BuiltListMultimap.toMap, BuiltSet.toSet, BuiltMap.toMap and BuiltSetMultimap.toMap.

Built Collections are Immutable #

Built Collections do not offer any methods that modify the collection. In order to make changes, first call toBuilder to get a mutable builder.

In particular, Built Collections do not implement or extend their mutable counterparts. BuiltList implements Iterable, but not List. BuiltSet implements Iterable, but not Set. BuiltMap, BuiltListMultimap and BuiltSetMultimap share no interface with the SDK collections.

Built Collections can contain mutable elements. However, this use is not recommended, as mutations to the elements will break comparison and hashing.

Built Collections are Comparable #

Core SDK collections do not offer equality checks by default.

Built Collections do a deep comparison against other Built Collections of the same type, only. Hashing is used to make repeated comparisons fast.

Built Collections are Hashable #

Core SDK collections do not compute a deep hashCode.

Built Collections do compute, and cache, a deep hashCode. That means they can be stored inside collections that need hashing, such as hash sets and hash maps. They also use the cached hash code to speed up repeated comparisons.

Built Collections Reject Nulls #

A null in a collection is usually a bug, so Built Collections and their builders throw if given a null element, key or value.

Built Collections Require Generic Type Parameters #

A List<dynamic> is error-prone because it can be assigned to a List of any type without warning. So, all Built Collections must be created with explicit element, key or value types.

Built Collections Reject Wrong-type Elements, Keys and Values #

Collections that happen to contain elements, keys or values that are not of the right type can lead to difficult-to-find bugs. So, all Built Collections and their builders are aggressive about validating types, even with checked mode disabled.

Built Collections Avoid Copying Unnecessarily #

Built Collections and their builder and helper types collaborate to avoid copying unless it's necessary.

In particular, BuiltList.toList, BuiltListMultimap.toMap, BuiltSet.toSet, BuiltMap.toMap and BuiltSetMultimap.toMap do not make a copy, but return a copy-on-write wrapper. So, Built Collections can be efficiently and easily used with code that needs core SDK collections but does not mutate them.

When you want to provide a collection that explicitly throws when a mutation is attempted, use BuiltList.asList, BuiltListMultimap.asMap, BuiltSet.asSet, BuiltSetMultimap.asMap and BuiltMap.asMap.

Features and bugs #

Please file feature requests and bugs at the issue tracker.

Changelog #

4.3.2 #

  • Add an example folder with some example code.

4.3.1 #

  • Internal: cleanup for pedantic v1.9.0 lints.

4.3.0 #

  • Add extensions methods: List.build, Set.build, Map.build, Iterable.toBuiltList and Iterable.toBuiltSet. Requires SDK 2.6.0.
  • Cleanup: remove unnecessary new and const.

4.2.2 #

  • Bug fix: ListMultimapBuilder.[] no longer ignores modifications under some circumstances.

4.2.1 #

  • Bug fix: ListBuilder first and last setters can no longer modify the underlying collection.

4.2.0 #

  • Add benchmark for VM and dart2js.
  • Stop doing explicit type checks on elements; in Dart 2 these are implied.
  • Modify methods on ListBuilder and SetBuilder that take Iterable elements so they only iterate over the iterable once. Improves performance when the iterable are slow/lazy.

4.1.0 #

  • Add return val to SetBuilder.add() to match Set.add().
  • Expand ListMultimapBuilder: implement [] and add return values to remove and removeAll.

4.0.0 #

  • Many changes following Dart 2 improvements to collections:
    • Implement Iterable methods: cast, followedBy and whereType.
    • Remove obsolete Iterable method: retype.
    • Support orElse in singleWhere.
    • Add BuiltList methods: +, indexWhere, lastIndexWhere.
    • Add ListBuilder setters and getters: first, last.
    • Add BuiltMap methods: entries, map.
    • Add MapBuilder methods: addEntries, updateValue, updateAllValues.
    • Implement Dart 2 methods in internal collections used by toList, toMap and toSet.
  • Add from and of constructors to BuiltList, BuiltMap and BuiltSet. The from constructors, like the current constructors, take collections of any type and check each element. The of constructors, like the SDK of constructors, take a collection of the correct type. This means they can be used for type inference, allowing you to omit the explicit type.
  • Make remove, removeAt and removeLast methods on builders return values like their SDK collection equivalents.

3.2.0 #

  • Add length, isEmpty and isNotEmpty to ListBuilder, MapBuilder and SetBuilder

3.1.3 #

  • Allow SDK 2.0.0.

3.1.2 #

  • Allow quiver 2.0.0, use test version 1.

3.1.1 #

  • Allow quiver 0.29.

3.1.0 #

  • Implement followedBy on BuiltList and BuiltSet.

3.0.5 #

  • Type fixes for DDC. Stop using a Map as a Map<K, V> in MapBuilder.

3.0.4 #

  • Tweaks to tests.

3.0.3 #

  • Allow quiver 0.28.

3.0.2 #

  • Stop using Function() syntax for Set and Map factories. It causes problems for the analyzer when using a pre-Dart-2 SDK.

3.0.1 #

  • Improve package description.

3.0.0 #

  • Prepare for Dart 2; add methods that will appear in Iterable.
  • Allow quiver 0.27.

2.1.3 #

  • Revert changes for Dart 2; they will be re-released as v3.0.0 as they are break libraries that provide their own implementations of built collections.

2.1.2 #

  • Fix changes for Dart 2.

2.1.1 #

  • Prepare for Dart 2; add methods that will appear in Iterable.

2.1.0 #

  • BuiltSet and BuiltMap now allow you to specify the underlying collection type. For example, you can construct a BuiltSet using a SplayTreeSet. This results in a set that is always in sorted order instead of preserving insertion order. Another useful possibility is to use a HashSet, which leads to a random order but improves performance over the default. See SetBuilder.withBase and MapBuilder.withBase.

2.0.0 #

  • Split collection classes into abstract interfaces and concrete, private, implementations. This allows new implementations of the interfaces. Note that this change is invisible unless you rely on the exact runtimeType of the collections.

1.6.2 #

  • Fix a bug whereby ListBuilder and MapBuilder allowed nulls to be introduced via map and expand.

1.6.1 #

  • Allow quiver 0.26.

1.6.0 #

  • The addIterable method is now generic. This allows the types of the functions passed in to be inferred.

1.5.0 #

  • Add BuiltIterable interface for when you want to accept a BuiltList or BuiltSet.

1.4.1 #

  • Use real generic syntax, drop comment-based syntax.

1.4.0 #

  • Add operator[] to ListBuilder and MapBuilder for easier inline updates.

1.3.1 #

  • Allow quiver 0.25.

1.3.0 #

  • Widen parameter of BuiltSet.difference and BuiltSet.intersection to BuiltSet<Object> to match Set.

1.2.0 #

  • Update for Set.difference change in SDK 1.21.0.
  • Add asList, asMap, and asSet to the built collection classes.

1.1.0 #

  • Remove runtime checks that are unnecessary if the project using built_collection is "strong mode clean", that is, if it has no errors with strong mode. See note in README.md about strong mode.

1.0.6 #

  • Allow quiver 0.23.

1.0.5 #

  • Strong mode clean.

1.0.4 #

  • Add reference identity check to equals operators.

1.0.3 #

  • Fix factories when iterable generic type is subtype of requested type.

1.0.2 #

  • Add generic type information to map, fold and expand methods.

1.0.1 #

  • Make map operator[] take Object instead of K, as SDK collections do.
  • Fix toString for result of toList, toSet, toMap.

1.0.0 #

  • Fix missing generics on some return types.
  • Fix BuiltList and BuiltSet "contains" method, should take Object, not E.
  • Add removeAll and retainAll methods to SetBuilder.
  • Add BuiltList.toBuiltSet() and BuiltSet.toBuiltList().
  • Add addIterable methods to Map and Multimap builders.

0.4.0 #

  • Add BuiltSetMultimap.

0.3.1 #

  • Fix "part of" statement.

0.3.0 #

  • Bug fix: fix Iterable "update in place" methods of BuiltList and BuiltSet so they discard original list or set.
  • Make keys and values stable for BuiltMap and BuiltMultimap.
  • Make repeated builds return identical instances for BuiltList, BuiltMap, BuiltSet.
  • Add 'replace' methods.

0.2.0 #

  • Add BuiltListMultimap.

0.1.1 #

  • Fix comments.

0.1.0 #

  • Add build and rebuild methods to BuiltList, BuiltMap, BuiltSet.
  • Add update methods to ListBuilder, MapBuilder, SetBuilder.

0.0.1 #

  • Initial version.


// Copyright (c) 2020, Google Inc. Please see the AUTHORS file for details.
// All rights reserved. Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

import 'package:built_collection/built_collection.dart';

void main() {
  // `built_collection` provides immutable equivalents of Dart SDK `List`,
  // `Set` and `Map`: `BuiltList`, `BuiltSet` and `BuiltMap`.

  // The easiest way to create them is from collection literals using `build`:
  var builtList = [1, 2, 3].build();
  var builtSet = {1, 2, 3}.build();
  var builtMap = {1: 'one', 2: 'two', 3: 'three'}.build();

  // `BuiltList` and `BuiltSet` can also be constructed from any `Iterable`.
  // The unnamed constructors act like the SDK `from` constructors, meaning
  // the elements are type checked at runtime.
  builtList = BuiltList([1, 2, 3]);
  builtSet = BuiltSet([1, 2, 3]);

  // Alternatively, the `of` constructors match the type to the `Iterable` you
  // pass, and so do not need to check the type of elements.
  builtList = BuiltList.of([1, 2, 3]);
  builtSet = BuiltSet.of([1, 2, 3]);

  // `BuiltMap` can be constructed from a `Map` or a `BuiltMap`.
  builtMap = BuiltMap({1: 'one', 2: 'two', 3: 'three'});

  // Immutable collections can't be updated, but you can create new instances
  // based on existing ones. The most convenient way to do that is the
  // `rebuild` methods, which give you access to each collection type's
  // corresponding builder type.

  // For example, to add some elements then sort:
  builtList = builtList.rebuild((b) => b
    ..addAll([7, 6, 5])

  // Generally, built collections match the SDK collections, except that the
  // API has been split in two: read only methods go on the `Built` collection
  // types, and mutating methods go on the corresponding `Builder` types.

  // If you need to keep a mutable version of the collection around for a
  // while, for example to pass it to other methods, you can use `toBuilder`.
  // Then, later, the collection is made immutable again by calling `build`.
  var listBuilder = builtList.toBuilder();
  listBuilder.addAll([10, 9, 8]);
  // More changes could go here, including passing the builder to other
  // methods.
  builtList = listBuilder.build();

  // Finally, `built_collection` also provides immutable versions of
  // `ListMultimap` and `SetMultimap` from `package:quiver`. For information
  // on these, and full details on all the APIs, please see the package
  // [dartdoc](https://pub.flutter-io.cn/documentation/built_collection/latest).

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  built_collection: ^4.3.2

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:built_collection/built_collection.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on May 30, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.2
  • pana: 0.13.8-dev


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.6.0 <3.0.0
collection ^1.7.0 1.14.12
quiver >=0.21.0 <3.0.0 2.1.3
Transitive dependencies
matcher 0.12.6
meta 1.1.8
path 1.7.0
stack_trace 1.9.3
Dev dependencies
pedantic ^1.4.0
test ^1.0.0