Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A List in Dart is an ordered, zero-indexed collection of objects. It serves as the Dart implementation of an array and utilizes generics (List<E>) to enforce compile-time type safety. A List implements the Iterable<E> interface, inheriting a wide array of functional collection methods.

​
Memory and Mutability Types

Dart lists operate in three primary mutability states regarding their length and element assignment:
  1. Growable (Default): Backed by a dynamic array. The internal buffer resizes automatically when the capacity is exhausted.
  2. Fixed-length: Memory is pre-allocated. Elements can be modified via index, but operations that alter the length (e.g., add, remove) throw an UnsupportedError.
  3. Unmodifiable: Neither the length nor the individual elements can be mutated.

​
Instantiation Syntax

Lists are typically instantiated using collection literals or factory constructors. 
// 1. Growable List Literal (Type inferred as List<int>)
var growableList = [1, 2, 3];

// 2. Fixed-length List Constructor
// Creates a list of length 3, initialized with 'A'.
List<String> fixedList = List.filled(3, 'A', growable: false);

// 3. Generated List Constructor
// Creates a list by invoking a callback for each index.
List<int> generatedList = List.generate(5, (index) => index * 2);

// 4. Unmodifiable List Constructor
List<double> lockedList = List.unmodifiable([1.1, 2.2, 3.3]);

​
Collection Operators

Dart provides specialized syntactic sugar for declarative list composition directly within literals.
  • Spread Operator (...): Unpacks an Iterable into the current list.
  • Null-aware Spread (...?): Unpacks an Iterable only if it is not null.
  • Collection if: Conditionally includes an element.
  • Collection for: Iterates and inserts elements inline.
List<int> baseList = [2, 3];
List<int>? nullList;
bool includeFour = true;

List<int> composedList = [
  1,
  ...baseList,          // Unpacks: 2, 3
  ...?nullList,         // Ignored because it is null
  if (includeFour) 4,   // Evaluates to: 4
  for (var i in baseList) i * 10 // Evaluates to: 20, 30
];
// Result: [1, 2, 3, 4, 20, 30]

​
Core API Surface

Because List<E> implements Iterable<E>, it shares many traversal methods but adds index-based access and mutation capabilities.

​
Inspection Properties

List<String> items = ['a', 'b', 'c'];

int len = items.length;       // 3
bool empty = items.isEmpty;   // false
String first = items.first;   // 'a' (Throws StateError if empty)
String last = items.last;     // 'c' (Throws StateError if empty)

​
Mutation Methods (Growable Lists Only)

List<int> nums = [1];

nums.add(2);                  // Appends single element: [1, 2]
nums.addAll([3, 4]);          // Appends iterable: [1, 2, 3, 4]
nums.insert(0, 0);            // Shifts elements right: [0, 1, 2, 3, 4]
nums.removeAt(2);             // Removes element at index 2: [0, 1, 3, 4]
nums.removeWhere((e) => e>3); // Removes based on predicate: [0, 1, 3]

​
Functional Transformations

Methods like map and where return a lazy Iterable<E>. To evaluate the iterable and allocate the result into a new concrete array in memory, .toList() must be invoked. 
List<int> values = [1, 2, 3, 4];

// Filtering (Returns lazy Iterable, evaluated into a new List)
List<int> evens = values.where((e) => e.isEven).toList();

// Transformation (Returns lazy Iterable, evaluated into a new List)
List<String> strings = values.map((e) => e.toString()).toList();

// Accumulation (Returns a single value of type E)
int sum = values.reduce((value, element) => value + element);
Master Dart with Deep Grasping Methodology!Learn More