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.
See below for details on each of these points.
Please note that from version
1.1.0 built_collection must be used in
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
It's okay to accept
Map if needed. Built Collections
provide efficient conversion to their SDK counterparts via
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
Iterable, but not
Iterable, but not
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.
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.
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.
null in a collection is usually a bug, so Built Collections and their
builders throw if given a
null element, key or value.
List<dynamic> is error-prone because it can be assigned to a
any type without warning. So, all Built Collections must be created with
explicit element, key or value types.
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 and their builder and helper types collaborate to avoid copying unless it's necessary.
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
Please file feature requests and bugs at the issue tracker.
ListMultimapBuilder.no longer ignores modifications under some circumstances.
lastsetters can no longer modify the underlying collection.
Iterableelements so they only iterate over the iterable once. Improves performance when the iterable are slow/lazy.
and add return values to
ListBuildersetters and getters:
fromconstructors, like the current constructors, take collections of any type and check each element. The
ofconstructors, like the SDK
ofconstructors, take a collection of the correct type. This means they can be used for type inference, allowing you to omit the explicit type.
removeLastmethods on builders return values like their SDK collection equivalents.
Mapfactories. It causes problems for the analyzer when using a pre-Dart-2 SDK.
BuiltMapnow allow you to specify the underlying collection type. For example, you can construct 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
runtimeTypeof the collections.
MapBuilderallowed nulls to be introduced via
BuiltSet<Object>to match Set.
asSetto the built collection classes.
README.mdabout strong mode.
Add this to your package's pubspec.yaml file:
dependencies: built_collection: ^4.2.2
You can install packages from the command line:
$ pub get
$ flutter pub get
Alternatively, your editor might support
pub get or
flutter pub get.
Check the docs for your editor to learn more.
Now in your Dart code, you can use:
|4.2.2||May 12, 2019|
|4.2.1||May 6, 2019|
|4.2.0||Apr 2, 2019|
|4.1.0||Dec 3, 2018|
|4.0.0||Aug 20, 2018|
|3.1.3||Jul 23, 2018|
|3.1.2||Jul 23, 2018|
|3.1.1||Mar 26, 2018|
|3.0.5||Feb 18, 2018|
|3.0.4||Jan 31, 2018|
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]
We analyzed this package on May 22, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
Detected platforms: Flutter, web, other
No platform restriction found in primary library
Maintain an example. (-10 points)
Create a short demo in the
example/ directory to show how to use this package.
Common filename patterns include
built_collection.dart. Packages with multiple examples should provide
For more information see the pub package layout conventions.