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 ~/= operator is a compound assignment operator that performs truncating division on the left operand by the right operand, assigning the resulting value back to the left operand. It combines the truncating division operator (~/) with the standard assignment operator (=), ensuring that the left operand is evaluated exactly once. 
leftOperand ~/= rightOperand;
While conceptually equivalent to leftOperand = leftOperand ~/ rightOperand, the ~/= operator evaluates leftOperand only a single time. This distinction is critical when the left operand is an expression with side effects (e.g., list[i++] ~/= 2). In the compound assignment, the side effect (i++) occurs exactly once, whereas the expanded form would trigger it twice.

​
Operator Overloading and Type Constraints

The exact behavior and return type of the ~/= operation depend on how the ~/ operator is defined for the left operand’s type:
  • Built-in num Types (int and double): For numeric types, ~/ divides the two numbers, discards any fractional part of the quotient, and strictly returns an int. Consequently, the leftOperand must be an assignable expression (an lvalue) of a type that accepts an int assignment (e.g., int, num, or dynamic). If the left operand is explicitly typed as a double, the operation triggers a compile-time error because Dart’s static type system prohibits assigning an int to a double.
  • Other Core Types (BigInt): The BigInt class implements operator ~/ to return a BigInt. Therefore, when using ~/= with BigInt operands, the result is a BigInt, and the left operand must accept a BigInt assignment.
  • Custom Classes: Dart supports operator overloading. Custom classes can define operator ~/ to return any arbitrary type. The only static constraint is that the left operand must be of a type that accepts the specific return type of that overloaded operator.

​
Runtime Exceptions (Built-in num Types)

When operating on built-in num types, if the rightOperand evaluates to 0, the operation throws an UnsupportedError. The specific exception message depends on the platform and the runtime type of the left operand:
  • Dart Native (VM/AOT): If the left operand holds an int value, integer division by zero throws an UnsupportedError specifically indicating “Integer division by zero”.
  • Dart Web (JavaScript Compilation): On the web, Dart integers are backed by JavaScript double-precision floating-point numbers. Consequently, int division by zero (e.g., 10 ~/ 0) evaluates to Infinity.truncate(). This throws an UnsupportedError indicating “Infinity or NaN toInt”.
  • Floating-Point Operands: If the left operand holds a double value at runtime (but is statically typed as num or dynamic to allow the assignment), the intermediate division evaluates to Infinity (or NaN). Dart then attempts to truncate this result to an integer, throwing an UnsupportedError indicating “Infinity or NaN toInt” across all platforms.

​
Execution Examples

// Standard integer truncating division
int x = 17;
x ~/= 5; 
// 1. Evaluates 17 ~/ 5, resulting in the integer 3.
// 2. Assigns 3 back to x.

// Dynamic/num typing allowing int assignment
num y = 10.5;
y ~/= 2.5;
// 1. Evaluates 10.5 ~/ 2.5, resulting in the integer 4.
// 2. Assigns 4 back to y.

// Single evaluation of side effects
List<int> values = [20, 30];
int index = 0;
values[index++] ~/= 6;
// Evaluates the left operand (values[0]) and the side effect (index++) exactly once.
// values[0] becomes 3, and index becomes 1.

// Operator overloading with BigInt
BigInt bigVal = BigInt.from(100);
bigVal ~/= BigInt.from(3);
// Evaluates to BigInt.from(33) and assigns it back to bigVal.

// Compile-time error due to type constraints on num types
// double z = 5.5;
// z ~/= 2; 
// ERROR: A value of type 'int' can't be assigned to a variable of type 'double'.
Master Dart with Deep Grasping Methodology!Learn More