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 constant pattern determines if a matched value is equal to a specific compile-time constant. It evaluates to true if the matched value and the constant are equivalent, strictly requiring the constant to have primitive equality.

​
Syntax

The syntax consists of a compile-time constant expression placed directly within a pattern matching context, such as a switch statement, switch expression, or if-case statement. 
switch (expression) {
  case constantExpression:
    // Executes if expression matches the constantExpression
}

​
The Primitive Equality Requirement

Dart strictly requires constant patterns to have primitive equality. A compile-time constant whose class overrides operator == cannot be used as a constant pattern. The pattern matching mechanism relies on compiler-enforced identity or primitive equivalence rather than invoking a custom == method at runtime. If a developer needs to match against a constant that belongs to a class overriding operator == (such as Point from dart:math), the constant pattern will fail to compile. Instead, the developer must use a relational pattern by explicitly prepending the equality operator: 
// Invalid: MyClass overrides ==
// case const MyClass(1): 

// Valid: Uses a relational pattern instead of a constant pattern
// case == const MyClass(1):

​
Valid Constant Expressions

A constant pattern accepts expressions that Dart evaluates as compile-time constants, provided they meet the primitive equality rule. This includes:
  • Primitive Literals: Integers (42), doubles (3.14), strings ('Dart'), booleans (true, false), and null. (Note: While String and double override ==, Dart’s specification explicitly grants them primitive equality status for pattern matching).
  • Named Constants: Variables explicitly declared with the const modifier, referencing primitive-equality types.
  • Enum Values: Specific members of an enumeration.
  • Constant Constructors: Object instances created using a const constructor, strictly on classes that do not override operator ==.
  • Constant Collections: Lists, sets, or maps instantiated with the const keyword.

​
Technical Mechanics

  1. Compile-Time Resolution: The pattern itself must be fully resolved at compile time. final variables or runtime-evaluated expressions are invalid.
  2. Canonicalization: Because constant patterns require primitive equality, Dart often relies on the canonicalization of const instances to perform rapid identity checks (identical()) under the hood.
  3. Type Promotion: If a constant pattern matches, it does not inherently promote the type of the matched variable. The match guarantees value equivalence, not strict type identity.

​
Code Visualization

The following example demonstrates valid constant patterns, including a custom class that adheres to the primitive equality rule by not overriding operator ==: 
const int maxRetries = 3;
enum ConnectionState { disconnected, connected }

// A class that does NOT override operator ==
class Marker {
  final String id;
  const Marker(this.id); 
}

void parseValue(dynamic value) {
  switch (value) {
    case 200:                           // Integer literal constant pattern
      print('OK');
    case 'Error':                       // String literal constant pattern
      print('String match');
    case null:                          // Null constant pattern
      print('Null match');
    case maxRetries:                    // Named constant pattern
      print('Named constant match');
    case ConnectionState.disconnected:  // Enum constant pattern
      print('Enum match');
    case const Marker('A'):             // Constant object pattern (primitive equality)
      print('Marker match');
    case const [1, 2, 3]:               // Constant collection pattern
      print('List match');
  }
}
Master Dart with Deep Grasping Methodology!Learn More