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 on clause in Dart is a contextual keyword used to establish strict type constraints or define target types across three distinct language constructs: exception handling, mixin declarations, and extension methods.

​
1. Exception Handling (Type Filtering)

In a try-catch statement, the on clause filters thrown exceptions based on their runtime type. It allows the control flow to branch into specific blocks only if the thrown object is a subtype of the specified type. Syntax: 
void processInput(String input) {
  try {
    int.parse(input);
  } on FormatException {
    // Executes if the exception matches FormatException.
    // The exception object is not bound to a variable.
  } on Exception catch (e, s) {
    // Executes if the exception is a subtype of Exception but not a FormatException.
    // Binds the exception to 'e' and the stack trace to 's'.
  } catch (e) {
    // Fallback for any other exception type (e.g., Error).
  }
}
Mechanics:
  • The clauses are evaluated sequentially from top to bottom.
  • It can be used standalone to handle an exception without binding the exception object to a local variable.
  • It can be combined with the catch clause when the exception object or stack trace is required in the local scope.

​
2. Mixin Constraints (Superclass Requirements)

When declaring a mixin, the on clause restricts the classes that are permitted to apply the mixin. It dictates that any class using the mixin with the with keyword must be a subtype of the type(s) specified in the on clause. Syntax: 
class RequiredSuperclass {
  void someSuperclassMethod() {}
}

mixin MixinName on RequiredSuperclass {
  void internalMethod() {
    // Can safely invoke methods from RequiredSuperclass
    super.someSuperclassMethod();
  }
}

// Valid application
class ValidClass extends RequiredSuperclass with MixinName {}

// Compiler Error: InvalidClass does not extend RequiredSuperclass
// class InvalidClass with MixinName {}
Mechanics:
  • By specifying an on type, the mixin gains access to the instance members of that type, allowing the use of super calls within the mixin’s body.
  • A mixin can declare multiple type constraints by separating them with commas (e.g., mixin M on TypeA, TypeB). The applying class must implement or extend all specified types.

​
3. Extension Declarations (Target Type Binding)

In extension methods, the on clause defines the static target type that receives the extended functionality. It binds the methods, getters, setters, and operators defined within the extension block to the specified type. Syntax: 
extension StringExtension on String {
  // Members injected into String
  bool get isCapitalized => isNotEmpty && this[0] == toUpperCase()[0];
}

// Generic target type binding
extension GenericExtension<T extends num> on List<T> {
  // Members injected into List<T> where T is a number
  double get sum => fold(0, (prev, element) => prev + element);
}
Mechanics:
  • The compiler uses the on type to resolve method calls statically at compile time.
  • It supports generics, allowing the on clause to bind to parameterized types and propagate type variables into the extension’s scope.
  • If the target type is nullable (e.g., on String?), the extension members can be invoked on null references, requiring internal null checks.
Master Dart with Deep Grasping Methodology!Learn More