Dart num - SyntBlaze

The num type in Dart is an abstract class that serves as the root of the numeric type hierarchy. It provides a common interface for all numeric values and is the direct superclass for Dart’s two concrete numeric types: int (integer values) and double (64-bit double-precision floating-point values). Because it is abstract, num cannot be directly instantiated; it acts as a polymorphic container for its subclasses.

Type Resolution and Polymorphism

When a variable is declared as num, the Dart compiler permits it to hold either an int or a double. The exact type is resolved at runtime based on the assigned value.

num a = 10;      // Compile-time type: num. Runtime type: int.
num b = 10.5;    // Compile-time type: num. Runtime type: double.

a = 20.5;        // Valid: 'a' can be reassigned to a double because its static type is num.

Platform-Specific Memory Representation

The underlying memory representation of num subclasses depends on the compilation target:

Native (Dart VM / AOT): int is represented as a 64-bit two’s complement integer. double is represented as an IEEE 754 64-bit double-precision floating-point number.
Web (JavaScript): Because JavaScript lacks a distinct integer type, both int and double are mapped to JavaScript’s Number type (IEEE 754 double-precision float). Consequently, on the web, int precision is restricted to $2^{53} - 1$ (the maximum safe integer in JavaScript).

Core Properties

The num class defines several standard properties to evaluate the state of the numeric value:

num value = -42.5;

bool finite = value.isFinite;     // true (not NaN or infinity)
bool infinite = value.isInfinite; // false
bool nan = value.isNaN;           // false (Not-a-Number check)
bool negative = value.isNegative; // true
num sign = value.sign;            // -1.0 (Returns -1, 0, or 1 based on polarity)

Core Methods

num provides a standard suite of mathematical and transformation methods inherited by both int and double: Type Conversion:

num val = 42.9;
int asInt = val.toInt();       // 42 (truncates the fractional part)
double asDouble = val.toDouble(); // 42.9

Rounding and Bounding:

num val = 42.5;
num absolute = val.abs();             // 42.5
int ceiling = val.ceil();             // 43
int floor = val.floor();              // 42
int rounded = val.round();            // 43
int truncated = val.truncate();       // 42
num clamped = val.clamp(45.0, 50.0);  // 45.0 (bounds the value between lower and upper limits)

Parsing

The num class provides static methods for parsing string literals into numeric types. The parser automatically infers whether to return an int or a double based on the presence of a decimal point or exponent.

num parsed1 = num.parse('42');      // Returns int: 42
num parsed2 = num.parse('42.5');    // Returns double: 42.5

// tryParse returns null instead of throwing a FormatException on failure
num? safeParse = num.tryParse('invalid_number'); // Returns null

Operator Restrictions

While num supports standard arithmetic operators (+, -, *, /, %, ~/), it does not support bitwise operators (&, |, ^, ~, <<, >>, >>>). Bitwise operations are strictly defined on the int class. To perform bitwise operations on a num variable, it must first be explicitly cast or converted to an int.

num x = 5;
num y = 3;

// num result = x & y; // COMPILATION ERROR: The operator '&' isn't defined for the class 'num'.
int result = x.toInt() & y.toInt(); // Valid