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 Pattern is a destructuring and matching construct in Dart that evaluates an object to determine if it implements the List interface, satisfies a specific length constraint, and matches a defined sequence of elements. It allows developers to simultaneously validate a list’s structural integrity and extract its elements into distinct variables using subpatterns.

​
Syntax and Mechanics

A list pattern is denoted by square brackets [] containing a comma-separated sequence of subpatterns. When a list pattern is evaluated against a value, it performs the following checks:
  1. Type Validation: The matched value must implement List<dynamic>.
  2. Length Validation: The list must match the length constraints defined by the pattern.
  3. Element Validation: Each element in the list must match the corresponding subpattern at the same index.

​
Exact Length Matching

By default, a list pattern enforces an exact length constraint. The target list must contain the exact number of elements as the subpatterns defined within the brackets. 
// Matches a list of exactly three elements.
// Binds the values at indices 0, 1, and 2 to variables a, b, and c.
var [a, b, c] = [10, 20, 30]; 

// Fails matching (throws an exception in a declaration context) 
// because the length does not match.
var [x, y] = [10, 20, 30];

​
The Rest Element (...)

To match lists of arbitrary lengths, Dart provides the rest element (...). It relaxes the exact length constraint, allowing the pattern to match zero or more elements that are not explicitly matched by other subpatterns.
  • A list pattern can contain a maximum of one rest element.
  • The rest element can be placed anywhere in the pattern (beginning, middle, or end).
  • It can optionally bind the unmatched elements into a new List variable.
// Matches a list of at least two elements.
// Binds index 0 to 'first', the last index to 'last', and ignores the middle.
var [first, ..., last] = [1, 2, 3, 4, 5];

// Binds the remaining elements into a new list called 'middle'.
var [first, ...middle, last] = [1, 2, 3, 4, 5]; 
// middle is [2, 3, 4]

​
Wildcards and Ignoring Elements (_)

If specific elements at given indices are irrelevant to the destructuring operation, the wildcard pattern (_) is used to discard them while maintaining the positional index for subsequent subpatterns. 
// Matches a list of exactly three elements.
// Extracts the second element, discarding the first and third.
var [_, second, _] = [10, 20, 30];

​
Type Arguments

List patterns can be explicitly typed to enforce the generic type of the list being matched. If a type argument is provided, the pattern will only match if the target object is a List of that specific type. 
// Matches only if the target is explicitly a List<int> of length 2.
switch (dynamicValue) {
  case <int>[int a, int b]:
    print('Matched a list of two integers');
}

​
Nested Subpatterns

Because each element in a list pattern is itself a pattern, list patterns can be deeply nested with other pattern types (such as Map patterns, Object patterns, or other List patterns) to destructure complex, multi-layered data structures. 
// Destructures a list containing another list at index 1.
var [a, [b, c]] = [1, [2, 3]];
Master Dart with Deep Grasping Methodology!Learn More