double abstract final

abstract final class double extends num

A double-precision floating point number.

Representation of Dart doubles containing double specific constants and operations and specializations of operations inherited from num. Dart doubles are 64-bit floating-point numbers as specified in the IEEE 754 standard.

The double type is contagious. Operations on doubles return double results.

It is a compile-time error for a class to attempt to extend or implement double.

See also:

• num the super class for double.
• Built-in number types
• Number representation

Inheritance

Object → num → double

Available Extensions

• DoubleAddress
• DoubleToJSNumber
• NumToJSExtension

Properties

address extension no setter

Pointer<Never> get address

The memory address of the underlying data.

An expression of the form expression.address denoting this address can only occurr as an entire argument expression in the invocation of a leaf Native external function.

Can only be used on fields of Struct subtypes, fields of Union subtypes, Array elements, or TypedData elements. In other words, the number whose address is being accessed must itself be acccessed through a Struct, Union, Array, or TypedData.

Example:

@Native<Void Function(Pointer<Float>)>(isLeaf: true)
external void myFunction(Pointer<Float> pointer);

final class MyStruct extends Struct {
  @Float()
  external double x;

  @Float()
  external double y;

  @Array(10)
  external Array<Float> array;
}

void main() {
  final myStruct = Struct.create<MyStruct>();
  myFunction(myStruct.y.address);
  myFunction(myStruct.array[5].address);

  final list = Float32List(10);
  myFunction(list[5].address);
}

The expression before .address is evaluated like the left-hand-side of an assignment, to something that gives access to the storage behind the expression, which can be used both for reading and writing. The .address then gives a native pointer to that storage.

The .address is evaluated just before calling into native code when invoking a leaf Native external function. This ensures the Dart garbage collector will not move the object that the address points in to.

Available on double, provided by the DoubleAddress extension

Implementation

external Pointer<Never> get address;

hashCode no setter inherited

int get hashCode

Returns a hash code for a numerical value.

The hash code is compatible with equality. It returns the same value for an int and a double with the same numerical value, and therefore the same value for the doubles zero and minus zero.

No guarantees are made about the hash code of NaN values.

Inherited from num.

Implementation

int get hashCode;

isFinite no setter inherited

bool get isFinite

Whether this number is finite.

The only non-finite numbers are NaN values, positive infinity, and negative infinity. All integers are finite.

All numbers satisfy exactly one of isInfinite, isFinite and isNaN.

Inherited from num.

Implementation

bool get isFinite;

isInfinite no setter inherited

bool get isInfinite

Whether this number is positive infinity or negative infinity.

Only satisfied by double.infinity and double.negativeInfinity.

All numbers satisfy exactly one of isInfinite, isFinite and isNaN.

Inherited from num.

Implementation

bool get isInfinite;

isNaN no setter inherited

bool get isNaN

Whether this number is a Not-a-Number value.

Is true if this number is the double.nan value or any other of the possible double NaN values. Is false if this number is an integer, a finite double or an infinite double (double.infinity or double.negativeInfinity).

All numbers satisfy exactly one of isInfinite, isFinite and isNaN.

Inherited from num.

Implementation

bool get isNaN;

isNegative no setter inherited

bool get isNegative

Whether this number is negative.

A number is negative if it's smaller than zero, or if it is the double -0.0. This precludes a NaN value like double.nan from being negative.

Inherited from num.

Implementation

bool get isNegative;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

sign no setter override

double get sign

The sign of the double's numerical value.

Returns -1.0 if the value is less than zero, +1.0 if the value is greater than zero, and the value itself if it is -0.0, 0.0 or NaN.

Implementation

double get sign;

toJS extension no setter

JSNumber get toJS

Converts this double to a JSNumber.

Available on double, provided by the DoubleToJSNumber extension

Implementation

external JSNumber get toJS;

toJS extension no setter

JSNumber get toJS

Converts this num to a JSNumber.

Available on num, provided by the NumToJSExtension extension

Implementation

JSNumber get toJS => DoubleToJSNumber(toDouble()).toJS;

Methods

abs() override

double abs()

The absolute value of this number.

The absolute value is the value itself, if the value is non-negative, and -value if the value is negative.

Integer overflow may cause the result of -value to stay negative.

print((2).abs()); // 2
print((-2.5).abs()); // 2.5

Implementation

double abs();

ceil() override

int ceil()

Returns the least integer that is not smaller than this number.

Rounds the number towards infinity.

Throws an UnsupportedError if this number is not finite (NaN or an infinity).

print(1.99999.ceil()); // 2
print(2.0.ceil()); // 2
print(2.00001.ceil()); // 3
print((-1.99999).ceil()); // -1
print((-2.0).ceil()); // -2
print((-2.00001).ceil()); // -2

Implementation

int ceil();

ceilToDouble() override

double ceilToDouble()

Returns the least integer double value no smaller than this.

If this is already an integer valued double, including -0.0, or it is not a finite value, the value is returned unmodified.

For the purpose of rounding, -0.0 is considered to be below 0.0. A number d in the range -1.0 < d < 0.0 will return -0.0.

print(1.99999.ceilToDouble()); // 2.0
print(2.0.ceilToDouble()); // 2.0
print(2.00001.ceilToDouble()); // 3.0
print((-1.99999).ceilToDouble()); // -1.0
print((-2.0).ceilToDouble()); // -2.0
print((-2.00001).ceilToDouble()); // -2.0

Implementation

double ceilToDouble();

clamp() inherited

num clamp(num lowerLimit, num upperLimit)

Returns this num clamped to be in the range lowerLimit-upperLimit.

The comparison is done using compareTo and therefore takes -0.0 into account. This also implies that double.nan is treated as the maximal double value.

The arguments lowerLimit and upperLimit must form a valid range where lowerLimit.compareTo(upperLimit) <= 0.

Example:

var result = 10.5.clamp(5, 10.0); // 10.0
result = 0.75.clamp(5, 10.0); // 5
result = (-10).clamp(-5, 5.0); // -5
result = (-0.0).clamp(-5, 5.0); // -0.0

Inherited from num.

Implementation

num clamp(num lowerLimit, num upperLimit);

compareTo() inherited

int compareTo(num other)

Compares this to other.

Returns a negative number if this is less than other, zero if they are equal, and a positive number if this is greater than other.

The ordering represented by this method is a total ordering of num values. All distinct doubles are non-equal, as are all distinct integers, but integers are equal to doubles if they have the same numerical value.

For doubles, the compareTo operation is different from the partial ordering given by operator==, operator< and operator>. For example, IEEE doubles impose that 0.0 == -0.0 and all comparison operations on NaN return false.

This function imposes a complete ordering for doubles. When using compareTo, the following properties hold:

• All NaN values are considered equal, and greater than any numeric value.
• -0.0 is less than 0.0 (and the integer 0), but greater than any non-zero negative value.
• Negative infinity is less than all other values and positive infinity is greater than all non-NaN values.
• All other values are compared using their numeric value.

Examples:

print(1.compareTo(2)); // => -1
print(2.compareTo(1)); // => 1
print(1.compareTo(1)); // => 0

// The following comparisons yield different results than the
// corresponding comparison operators.
print((-0.0).compareTo(0.0));  // => -1
print(double.nan.compareTo(double.nan));  // => 0
print(double.infinity.compareTo(double.nan)); // => -1

// -0.0, and NaN comparison operators have rules imposed by the IEEE
// standard.
print(-0.0 == 0.0); // => true
print(double.nan == double.nan);  // => false
print(double.infinity < double.nan);  // => false
print(double.nan < double.infinity);  // => false
print(double.nan == double.infinity);  // => false

Inherited from num.

Implementation

int compareTo(num other);

floor() override

int floor()

Returns the greatest integer no greater than this number.

Rounds the number towards negative infinity.

Throws an UnsupportedError if this number is not finite (NaN or infinity).

print(1.99999.floor()); // 1
print(2.0.floor()); // 2
print(2.99999.floor()); // 2
print((-1.99999).floor()); // -2
print((-2.0).floor()); // -2
print((-2.00001).floor()); // -3

Implementation

int floor();

floorToDouble() override

double floorToDouble()

Returns the greatest integer double value no greater than this.

If this is already an integer valued double, including -0.0, or it is not a finite value, the value is returned unmodified.

For the purpose of rounding, -0.0 is considered to be below 0.0. A number d in the range 0.0 < d < 1.0 will return 0.0.

print(1.99999.floorToDouble()); // 1.0
print(2.0.floorToDouble()); // 2.0
print(2.99999.floorToDouble()); // 2.0
print((-1.99999).floorToDouble()); // -2.0
print((-2.0).floorToDouble()); // -2.0
print((-2.00001).floorToDouble()); // -3.0

Implementation

double floorToDouble();

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

remainder() override

double remainder(num other)

The remainder of the truncating division of this by other.

The result r of this operation satisfies: this == (this ~/ other) * other + r. As a consequence, the remainder r has the same sign as the dividend this.

The result is an int, as described by int.remainder, if both this number and other are integers, otherwise the result is a double.

Example:

print(5.remainder(3)); // 2
print(-5.remainder(3)); // -2
print(5.remainder(-3)); // 2
print(-5.remainder(-3)); // -2

Implementation

double remainder(num other);

round() override

int round()

Returns the integer closest to this number.

Rounds away from zero when there is no closest integer: (3.5).round() == 4 and (-3.5).round() == -4.

Throws an UnsupportedError if this number is not finite (NaN or an infinity).

print(3.0.round()); // 3
print(3.25.round()); // 3
print(3.5.round()); // 4
print(3.75.round()); // 4
print((-3.5).round()); // -4

Implementation

int round();

roundToDouble() override

double roundToDouble()

Returns the integer double value closest to this.

Rounds away from zero when there is no closest integer: (3.5).roundToDouble() == 4 and (-3.5).roundToDouble() == -4.

If this is already an integer valued double, including -0.0, or it is not a finite value, the value is returned unmodified.

For the purpose of rounding, -0.0 is considered to be below 0.0, and -0.0 is therefore considered closer to negative numbers than 0.0. This means that for a value d in the range -0.5 < d < 0.0, the result is -0.0.

print(3.0.roundToDouble()); // 3.0
print(3.25.roundToDouble()); // 3.0
print(3.5.roundToDouble()); // 4.0
print(3.75.roundToDouble()); // 4.0
print((-3.5).roundToDouble()); // -4.0

Implementation

double roundToDouble();

toDouble() inherited

double toDouble()

This number as a double.

If an integer number is not precisely representable as a double, an approximation is returned.

Inherited from num.

Implementation

double toDouble();

toInt() inherited

int toInt()

Truncates this num to an integer and returns the result as an int.

Equivalent to truncate.

Inherited from num.

Implementation

int toInt();

toString() override

String toString()

Provide a representation of this double value.

The representation is a number literal such that the closest double value to the representation's mathematical value is this double.

Returns "NaN" for the Not-a-Number value. Returns "Infinity" and "-Infinity" for positive and negative Infinity. Returns "-0.0" for negative zero.

For all doubles, d, converting to a string and parsing the string back gives the same value again: d == double.parse(d.toString()) (except when d is NaN).

Implementation

String toString();

toStringAsExponential() inherited

String toStringAsExponential([int? fractionDigits])

An exponential string-representation of this number.

Converts this number to a double before computing the string representation.

If fractionDigits is given, then it must be an integer satisfying: 0 <= fractionDigits <= 20. In this case the string contains exactly fractionDigits after the decimal point. Otherwise, without the parameter, the returned string uses the shortest number of digits that accurately represent this number.

If fractionDigits equals 0, then the decimal point is omitted. Examples:

1.toStringAsExponential();       // 1e+0
1.toStringAsExponential(3);      // 1.000e+0
123456.toStringAsExponential();  // 1.23456e+5
123456.toStringAsExponential(3); // 1.235e+5
123.toStringAsExponential(0);    // 1e+2

Inherited from num.

Implementation

String toStringAsExponential([int? fractionDigits]);

toStringAsFixed() inherited

String toStringAsFixed(int fractionDigits)

A decimal-point string-representation of this number.

Converts this number to a double before computing the string representation, as by toDouble.

If the absolute value of this is greater than or equal to 10^21, then this methods returns an exponential representation computed by this.toStringAsExponential(). Otherwise the result is the closest string representation with exactly fractionDigits digits after the decimal point. If fractionDigits equals 0, then the decimal point is omitted.

The parameter fractionDigits must be an integer satisfying: 0 <= fractionDigits <= 20.

Examples:

1.toStringAsFixed(3);  // 1.000
(4321.12345678).toStringAsFixed(3);  // 4321.123
(4321.12345678).toStringAsFixed(5);  // 4321.12346
123456789012345.toStringAsFixed(3);  // 123456789012345.000
10000000000000000.toStringAsFixed(4); // 10000000000000000.0000
5.25.toStringAsFixed(0); // 5

Inherited from num.

Implementation

String toStringAsFixed(int fractionDigits);

toStringAsPrecision() inherited

String toStringAsPrecision(int precision)

A string representation with precision significant digits.

Converts this number to a double and returns a string representation of that value with exactly precision significant digits.

The parameter precision must be an integer satisfying: 1 <= precision <= 21.

Examples:

1.toStringAsPrecision(2);       // 1.0
1e15.toStringAsPrecision(3);    // 1.00e+15
1234567.toStringAsPrecision(3); // 1.23e+6
1234567.toStringAsPrecision(9); // 1234567.00
12345678901234567890.toStringAsPrecision(20); // 12345678901234567168
12345678901234567890.toStringAsPrecision(14); // 1.2345678901235e+19
0.00000012345.toStringAsPrecision(15); // 1.23450000000000e-7
0.0000012345.toStringAsPrecision(15);  // 0.00000123450000000000

Inherited from num.

Implementation

String toStringAsPrecision(int precision);

truncate() override

int truncate()

Returns the integer obtained by discarding any fractional part of this number.

Rounds the number towards zero.

Throws an UnsupportedError if this number is not finite (NaN or an infinity).

print(2.00001.truncate()); // 2
print(1.99999.truncate()); // 1
print(0.5.truncate()); // 0
print((-0.5).truncate()); // 0
print((-1.5).truncate()); // -1
print((-2.5).truncate()); // -2

Implementation

int truncate();

truncateToDouble() override

double truncateToDouble()

Returns the integer double value obtained by discarding any fractional digits from this.

If this is already an integer valued double, including -0.0, or it is not a finite value, the value is returned unmodified.

For the purpose of rounding, -0.0 is considered to be below 0.0. A number d in the range -1.0 < d < 0.0 will return -0.0, and in the range 0.0 < d < 1.0 it will return 0.0.

print(2.5.truncateToDouble()); // 2.0
print(2.00001.truncateToDouble()); // 2.0
print(1.99999.truncateToDouble()); // 1.0
print(0.5.truncateToDouble()); // 0.0
print((-0.5).truncateToDouble()); // -0.0
print((-1.5).truncateToDouble()); // -1.0
print((-2.5).truncateToDouble()); // -2.0

Implementation

double truncateToDouble();

Operators

operator %() override

double operator %(num other)

Euclidean modulo of this number by other.

Returns the remainder of the Euclidean division. The Euclidean division of two integers a and b yields two integers q and r such that a == b * q + r and 0 <= r < b.abs().

The Euclidean division is only defined for integers, but can be easily extended to work with doubles. In that case, q is still an integer, but r may have a non-integer value that still satisfies 0 <= r < |b|.

The sign of the returned value r is always positive.

See remainder for the remainder of the truncating division.

The result is an int, as described by int.%, if both this number and other are integers, otherwise the result is a double.

Example:

print(5 % 3); // 2
print(-5 % 3); // 1
print(5 % -3); // 2
print(-5 % -3); // 1

Implementation

double operator %(num other);

operator *() override

double operator *(num other)

Multiplies this number by other.

The result is an int, as described by int.*, if both this number and other are integers, otherwise the result is a double.

Implementation

double operator *(num other);

operator +() override

double operator +(num other)

Adds other to this number.

The result is an int, as described by int.+, if both this number and other is an integer, otherwise the result is a double.

Implementation

double operator +(num other);

operator -() override

double operator -(num other)

Subtracts other from this number.

The result is an int, as described by int.-, if both this number and other is an integer, otherwise the result is a double.

Implementation

double operator -(num other);

operator /() override

double operator /(num other)

Divides this number by other.

Implementation

double operator /(num other);

operator <() inherited

bool operator <(num other)

Whether this number is numerically smaller than other.

Returns true if this number is smaller than other. Returns false if this number is greater than or equal to other or if either value is a NaN value like double.nan.

Inherited from num.

Implementation

bool operator <(num other);

operator <=() inherited

bool operator <=(num other)

Whether this number is numerically smaller than or equal to other.

Returns true if this number is smaller than or equal to other. Returns false if this number is greater than other or if either value is a NaN value like double.nan.

Inherited from num.

Implementation

bool operator <=(num other);

operator ==() inherited

bool operator ==(Object other)

Test whether this value is numerically equal to other.

If both operands are doubles, they are equal if they have the same representation, except that:

• zero and minus zero (0.0 and -0.0) are considered equal. They both have the numerical value zero.
• NaN is not equal to anything, including NaN. If either operand is NaN, the result is always false.

If one operand is a double and the other is an int, they are equal if the double has an integer value (finite with no fractional part) and the numbers have the same numerical value.

If both operands are integers, they are equal if they have the same value.

Returns false if other is not a num.

Notice that the behavior for NaN is non-reflexive. This means that equality of double values is not a proper equality relation, as is otherwise required of operator==. Using NaN in, e.g., a HashSet will fail to work. The behavior is the standard IEEE-754 equality of doubles.

If you can avoid NaN values, the remaining doubles do have a proper equality relation, and can be used safely.

Use compareTo for a comparison that distinguishes zero and minus zero, and that considers NaN values as equal.

Inherited from num.

Implementation

bool operator ==(Object other);

operator >() inherited

bool operator >(num other)

Whether this number is numerically greater than other.

Returns true if this number is greater than other. Returns false if this number is smaller than or equal to other or if either value is a NaN value like double.nan.

Inherited from num.

Implementation

bool operator >(num other);

operator >=() inherited

bool operator >=(num other)

Whether this number is numerically greater than or equal to other.

Returns true if this number is greater than or equal to other. Returns false if this number is smaller than other or if either value is a NaN value like double.nan.

Inherited from num.

Implementation

bool operator >=(num other);

operator unary-() override

double operator unary-()

Subtracts other from this number.

The result is an int, as described by int.-, if both this number and other is an integer, otherwise the result is a double.

Implementation

double operator -();

operator ~/() override

int operator ~/(num other)

Truncating division operator.

Performs truncating division of this number by other. Truncating division is division where a fractional result is converted to an integer by rounding towards zero.

If both operands are ints, then other must not be zero. Then a ~/ b corresponds to a.remainder(b) such that a == (a ~/ b) * b + a.remainder(b).

If either operand is a double, then the other operand is converted to a double before performing the division and truncation of the result. Then a ~/ b is equivalent to (a / b).truncate(). This means that the intermediate result of the double division must be a finite integer (not an infinity or double.nan).

Implementation

int operator ~/(num other);

Static Methods

parse() override

double parse(String source)

Parse source as a double literal and return its value.

Accepts an optional sign (+ or -) followed by either the characters "Infinity", the characters "NaN" or a floating-point representation. A floating-point representation is composed of a mantissa and an optional exponent part. The mantissa is either a decimal point (.) followed by a sequence of (decimal) digits, or a sequence of digits optionally followed by a decimal point and optionally more digits. The (optional) exponent part consists of the character "e" or "E", an optional sign, and one or more digits. The source must not be null.

Leading and trailing whitespace is ignored.

Throws a FormatException if the source string is not a valid double literal.

Rather than throwing and immediately catching the FormatException, instead use tryParse to handle a potential parsing error.

Examples of accepted strings:

"3.14"
"  3.14 \xA0"
"0."
".0"
"-1.e3"
"1234E+7"
"+.12e-9"
"-NaN"

Implementation

external static double parse(String source);

tryParse() override

double? tryParse(String source)

Parse source as a double literal and return its value.

Like parse, except that this function returns null for invalid inputs instead of throwing.

Example:

var value = double.tryParse('3.14'); // 3.14
value = double.tryParse('  3.14 \xA0'); // 3.14
value = double.tryParse('0.'); // 0.0
value = double.tryParse('.0'); // 0.0
value = double.tryParse('-1.e3'); // -1000.0
value = double.tryParse('1234E+7'); // 12340000000.0
value = double.tryParse('+.12e-9'); // 1.2e-10
value = double.tryParse('-NaN'); // NaN
value = double.tryParse('0xFF'); // null
value = double.tryParse(double.infinity.toString()); // Infinity

Implementation

external static double? tryParse(String source);

Constants

infinity

const double infinity

Implementation

static const double infinity = 1.0 / 0.0;

maxFinite

const double maxFinite

Implementation

static const double maxFinite = 1.7976931348623157e+308;

minPositive

const double minPositive

Implementation

static const double minPositive = 5e-324;

nan

const double nan

Implementation

static const double nan = 0.0 / 0.0;

negativeInfinity

const double negativeInfinity

Implementation

static const double negativeInfinity = -infinity;