> ## 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.
# Dart Constant Pattern
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.
```dart theme={"dark"}
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:
```dart theme={"dark"}
// 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 ==`:
```dart theme={"dark"}
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');
}
}
```
Tired of Poor Dart Skills? Fix That With Deep Grasping!
Learn More
