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.

An operator method in Dart is a specialized instance method that redefines the behavior of standard lexical operators for user-defined classes. By declaring a method with the operator keyword followed by the target operator symbol, developers implement custom operator overloading, allowing class instances to be manipulated using standard mathematical, logical, or indexing syntax.

​
Syntax

The declaration of an operator method strictly follows this signature pattern: 
ReturnType operator <symbol>(ParameterType parameter) {
  // Implementation
}

​
Arity and Parameter Rules

The number of parameters an operator method accepts is strictly dictated by the arity of the operator being overridden. The left-hand operand is always the receiving instance (this).
  • Unary Operators: Accept exactly zero parameters. The operation is performed entirely on this.
ReturnType operator ~() => ...
ReturnType operator -() => ... // Unary minus (negation)
  • Binary Operators: Accept exactly one parameter, representing the right-hand operand.
ReturnType operator +(ParameterType other) => ...
ReturnType operator -(ParameterType other) => ... // Binary subtraction
Note on the minus operator: Dart distinguishes between the unary minus (negation) and binary minus (subtraction) entirely by the method’s arity. Declaring operator -() with zero parameters overloads the unary minus, while declaring operator -(ParameterType other) with one parameter overloads binary subtraction.
  • Index Operators:
    • The read index operator [] accepts exactly one parameter (the index).
    • The write index operator []= accepts exactly two parameters (the index and the value to assign).
ReturnType operator [](IndexType index) => ...
void operator []=(IndexType index, ValueType value) { ... }

​
Overridable Operators

Dart restricts operator overloading to a specific subset of lexical tokens. Only the following operators can be defined as methods:
  • Arithmetic: +, - (both unary and binary), *, /, ~/ (integer division), %
  • Relational: ==, <, >, <=, >=
  • Bitwise: ~, &, |, ^, <<, >>, >>>
  • Index: [], []=

​
Non-Overridable Operators

The Dart compiler enforces strict semantic consistency for certain operations, making the following operators ineligible for overloading:
  • Logical: &&, ||, !
  • Assignment: =, ??=
  • Compound Assignment: +=, -=, *=, etc. (These are implicitly resolved by the compiler using the base operator, e.g., a += b evaluates to a = a + b).
  • Inequality: != (The compiler automatically derives this by evaluating !(a == b)).
  • Type Test/Cast: is, is!, as
  • Control Flow / Null-Aware: ?:, ??, ?., .

​
Architectural Constraints

  1. The == Contract: When overriding the equality operator (==), the parameter type must be exactly Object. You do not need to use Object? because Dart’s compiler automatically short-circuits null comparisons (e.g., a == null) before the instance method is ever invoked, guaranteeing that other will be non-null. Furthermore, overriding == mandates a corresponding override of the hashCode getter to maintain the integrity of hash-based collections (like Set and Map).
@override
bool operator ==(Object other) {
  if (identical(this, other)) return true;
  return other is MyClass && other.internalValue == internalValue;
}

@override
int get hashCode => internalValue.hashCode;
  1. Instance Bound: Operator methods must be instance methods. They cannot be declared as static.
  2. Extension Methods: Operators can be added to existing types (including built-in types) using Dart’s extension feature, provided the underlying type does not already define that specific operator method.
Master Dart with Deep Grasping Methodology!Learn More