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 cast pattern in Dart allows you to assert the type of a matched value during pattern matching and destructuring. It uses the as keyword to perform a downcast, throwing a TypeError at runtime if the matched value does not conform to the specified type, rather than silently failing the match.

​
Syntax

<pattern> as <type>
The cast pattern consists of an inner pattern followed by the as keyword and a type annotation.

​
Mechanics

During runtime execution, a cast pattern evaluates an incoming value through the following strict sequence:
  1. Casting: The Dart runtime applies the as <type> operation to the incoming value first. If the value is not of the specified <type>, a TypeError is thrown immediately, halting the pattern match.
  2. Matching: If the cast succeeds, the runtime then evaluates the newly cast value against the inner <pattern>.
  3. Binding: If the inner pattern is a variable pattern, the variable is bound with the static type defined by <type>.
Because it utilizes Dart’s standard as operator, a cast pattern does not alter the control flow by rejecting a match if the type is incorrect. Instead, an invalid type assertion results in an unhandled runtime exception.

​
Syntax Visualization

In Variable Declarations (Destructuring): 
// Casts the first element to an int, then binds it to 'a'.
// Throws a TypeError if the element is not an int.
final [a as int, b] = someList;
In Switch Cases: 
switch (dynamicValue) {
  // Casts dynamicValue to String, then matches against 'var x'.
  // Throws if dynamicValue is not a String.
  case var x as String:
    print(x.length); // x is statically typed as String
    break;
}
Nested within Object Patterns: 
// Destructures a record, casting the 'value' field to a double before binding to 'v'.
final (id: _, value: v as double) = someRecord;

​
Cast Pattern vs. Safe Type Matching

It is critical to distinguish the cast pattern (as) from patterns that safely test types without throwing exceptions, such as typed wildcard patterns or typed variable patterns.
  • Typed Wildcard Pattern (<type> _): Acts as a guard. If the value is not of the specified type, the pattern match fails, and execution proceeds to the next case. It tests the type without binding the value to a variable.
  • Typed Variable Pattern (<type> <name>): Declares a variable with a type annotation. It also acts as a guard, failing gracefully if the type does not match, but binds the value to a variable if successful.
  • Cast Pattern (<pattern> as <type>): Acts as an assertion. It assumes the match is valid and forces the type evaluation first. If the value is not of the specified type, the program throws a TypeError.
Note: Never use a bare type literal (e.g., case String:) to test a type. This creates a Constant Pattern that matches the Type object itself, not instances of that type. 
switch (dynamicValue) {
  // Typed Wildcard Pattern: Fails gracefully, moves to next case. Does not bind.
  case String _:
    break;

  // Typed Variable Pattern: Fails gracefully, moves to next case. Binds to 's'.
  case String s:
    break;

  // Cast Pattern: Throws TypeError if not a String. Binds to 's'.
  case var s as String: 
    break;
}
Master Dart with Deep Grasping Methodology!Learn More