double abstract final#

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

Properties#

address extension no setter#

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

external Pointer<Never> get address;

hashCode no setter inherited#

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.

int get hashCode;

isFinite no setter inherited#

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.

bool get isFinite;

isInfinite no setter inherited#

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.

bool get isInfinite;

isNaN no setter inherited#

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.

bool get isNaN;

isNegative no setter inherited#

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.

bool get isNegative;

runtimeType no setter inherited#

A representation of the runtime type of the object.

Inherited from Object.

external Type get runtimeType;

sign no setter override#

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.

double get sign;

toJS extension no setter#

Converts this double to a JSNumber.

Available on double, provided by the DoubleToJSNumber extension

external JSNumber get toJS;

toJS extension no setter#

Converts this num to a JSNumber.

Available on num, provided by the NumToJSExtension extension

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

Methods#

abs() override#

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

double abs();

ceil() override#

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

int ceil();

ceilToDouble() override#

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

double ceilToDouble();

clamp() inherited#

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.

num clamp(num lowerLimit, num upperLimit);

compareTo() inherited#

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.

int compareTo(num other);

floor() override#

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

int floor();

floorToDouble() override#

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

double floorToDouble();

noSuchMethod() inherited#

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.

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

remainder() override#

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

double remainder(num other);

round() override#

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

int round();

roundToDouble() override#

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

double roundToDouble();

toDouble() inherited#

This number as a double.

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

Inherited from num.

double toDouble();

toInt() inherited#

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

Equivalent to truncate.

Inherited from num.

int toInt();

toString() override#

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).

String toString();

toStringAsExponential() inherited#

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.

String toStringAsExponential([int? fractionDigits]);

toStringAsFixed() inherited#

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.

String toStringAsFixed(int fractionDigits);

toStringAsPrecision() inherited#

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.

String toStringAsPrecision(int precision);

truncate() override#

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

int truncate();

truncateToDouble() override#

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

double truncateToDouble();

Operators#

operator %() override#

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

double operator %(num other);

operator *() override#

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.

double operator *(num other);

operator +() override#

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.

double operator +(num other);

operator -() override#

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.

double operator -(num other);

operator /() override#

Divides this number by other.

double operator /(num other);

operator <() inherited#

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.

bool operator <(num other);

operator <=() inherited#

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.

bool operator <=(num other);

operator ==() inherited#

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.

bool operator ==(Object other);

operator >() inherited#

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.

bool operator >(num other);

operator >=() inherited#

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.

bool operator >=(num other);

operator unary-() override#

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.

double operator -();

operator ~/() override#

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).

int operator ~/(num other);

Static Methods#

parse() override#

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"

external static double parse(String source);

tryParse() override#

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

external static double? tryParse(String source);

Constants#

infinity#

static const double infinity = 1.0 / 0.0;

maxFinite#

static const double maxFinite = 1.7976931348623157e+308;

minPositive#

static const double minPositive = 5e-324;

nan#

static const double nan = 0.0 / 0.0;

negativeInfinity#

static const double negativeInfinity = -infinity;