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.

The as operator in Dart is a typecast operator used to explicitly evaluate an expression as a specific static type at runtime. Rather than overriding the compiler’s static type inference, the as operator explicitly defines the static type of the cast expression itself. The Dart analyzer then uses this explicit type to inform static analysis and type inference for the surrounding code, while the runtime environment strictly enforces the cast. 
expression as Type

​
Runtime Behavior

The as operator performs a strict runtime type check. Its behavior depends entirely on the relationship between the runtime type of the expression and the target Type:
  • Successful Cast: If the runtime type of the expression is equivalent to or a subtype of Type, the operation succeeds. The expression is evaluated and returned as the target Type.
  • Failed Cast: If the runtime type of the expression is not a subtype of Type, the cast fails, and the Dart runtime immediately throws a TypeError. Because of this behavior, as is considered an unsafe cast.

​
Nullability Mechanics

The as operator strictly enforces Dart’s sound null safety system during the cast:
  • Non-nullable Target (as T): If the expression evaluates to null and the target Type is non-nullable, the runtime throws a TypeError.
  • Nullable Target (as T?): If the expression evaluates to null and the target Type is nullable, the cast succeeds and evaluates to null.

​
Type Promotion and the is Operator

While as forces a cast, Dart provides the is operator for safe type checking. When an is check evaluates to true, Dart automatically promotes the type of the local variable within that execution scope (smart casting). Because as throws an exception upon failure, using is is the preferred approach for safe type resolution. The as operator should generally only be used when the developer is absolutely certain of the underlying runtime type, but the static analyzer lacks the context to prove it.

​
Syntax Visualization

void main() {
  // A variable statically typed as 'num' but holding an 'int' at runtime
  num numericValue = 42;

  // 1. Successful downcast
  // The runtime type (int) is a subtype of the target type (int).
  int integerValue = numericValue as int;

  // 2. Failed cast
  // Passes static analysis (a 'num' can theoretically be a 'double'), 
  // but fails at runtime because the actual runtime type ('int') is NOT a subtype of 'double'.
  try {
    double doubleValue = numericValue as double;
  } on TypeError catch (e) {
    // Catches the thrown TypeError to prevent execution halt
    print('Cast failed: $e'); 
  }

  // 3. Nullability enforcement
  dynamic nullValue = null;

  // Succeeds: Target type is nullable. Evaluates to null.
  String? nullableString = nullValue as String?;

  // Fails: Target type is non-nullable. Throws a TypeError.
  try {
    String nonNullableString = nullValue as String;
  } on TypeError catch (e) {
    print('Null cast failed: $e');
  }
  
  // 4. The 'is' operator and type promotion (Preferred approach)
  if (numericValue is int) {
    // numericValue is automatically promoted to 'int' in this scope.
    // No 'as' operator is needed to access int-specific properties.
    print(numericValue.isEven); 
  }
}
Master Dart with Deep Grasping Methodology!Learn More