rspec/rules/S7089/dart/rule.adoc

Chain of https://api.dart.dev/stable/dart-core/List/add.html[`List<E>.add`] or https://api.dart.dev/stable/dart-core/List/addAll.html[`List<E>.addAll`] operations should be replaced by a single inline list literal.

== Why is this an issue?

Initializing a list with a chain of `add` or `addAll` invocations is less efficient than making the initialization with a single list literal. Each invocation has a cost in itself, and each list argument of the `addAll` method is instantiated to only be temporarily used for the insertion.

Invoking a method that includes lists constructed using such a pattern may lead to performance issues, on CPU usage as well as on memory allocations.  

On top of the performance argument, the list literal is more concise and easier to read.

=== Exceptions

The rule does not apply to other collection literals that expose the `add` or `addAll` methods, such as ``Set``s.

[source,dart]
----
final aSet = <int>{}..add(3)..add(4); // Not applicable
----

The rule does not apply when the chain of invocations doesn't start with a `List` literal:

[source,dart]
----
final aList = ...;
aList..add(43)..add(44);       // Not applicable
l1..addAll([43, 44])..add(45); // Not applicable
----

== How to fix it

Introduce a single list literal that includes all the elements that are added to the list as arguments of the `add` or `addAll` invocations in the chain.

=== Code examples

==== Noncompliant code example

[source,dart,diff-id=1,diff-type=noncompliant]
----
final aList = [42]..add(43)..addAll([44, anInt]);
----

==== Compliant solution

[source,dart,diff-id=1,diff-type=compliant]
----
final aList = [42, 43, 44, anInt];
----

== Resources

=== Documentation

* Dart Docs - https://dart.dev/tools/linter-rules/prefer_inlined_adds[Dart Linter - prefer_inlined_adds]
* Dart Docs - https://dart.dev/language/operators#cascade-notation[Dart Cascade Notation]
* Dart API Reference - https://api.dart.dev/stable/dart-core/List/add.html[`List<E>.add`]

=== Related rules

* S3257 - Collection literals should be preferred
* S7090 - Spread collections should be preferred to chaining list insertions

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

* When `add` is used: The addition of a list item could be inlined.
* When `addAll` is used: The addition of multiple list items could be inlined.

=== Highlighting

The first method invocation in the chain, whether it's `add` or `addAll`.

endif::env-github,rspecator-view[]