sdk/lib/core/num.dart - sdk.git - Git at Google

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.

 part of dart.core;

 /// An integer or floating-point number.
 ///
 /// It is a compile-time error for any type other than [int] or [double]
 /// to attempt to extend or implement `num`.
 abstract class num implements Comparable<num> {
   /// Test whether this value is numerically equal to `other`.
   ///
   /// If both operands are [double]s, 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.
   bool operator ==(Object other);

   /// 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.
   int get hashCode;

   /// 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
   /// ```
   int compareTo(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].
   num 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].
   num operator -(num other);

   /// Multiplies this number by [other].
   ///
   /// The result is an [int], as described by [int.*],
   /// if both this number and [other] is an integer,
   /// otherwise the result is a [double].
   num 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 stil 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] is an integer,
   /// otherwise the result is a [double].
   num operator %(num other);

   /// Divides this number by [other].
   double operator /(num other);

   /// Truncating division operator.
   ///
   /// If either operand is a [double] then the result of the truncating division
   /// `a ~/ b` is equivalent to `(a / b).truncate().toInt()`.
   ///
   /// If both operands are [int]s then `a ~/ b` performs the truncating
   /// integer division.
   int operator ~/(num other);

   /// The negation of this value.
   ///
   /// The negation of a number is a number of the same kind
   /// (`int` or `double`) representing the negation of the
   /// numbers numerical value (the result of subtracting the
   /// number from zero), if that value *exists*.
   ///
   /// Negating a double gives a number with same magnitude
   /// as the original value (`number.abs() == (-number).abs()`),
   /// and the opposite sign (`-(number.sign) == (-number).sign`).
   ///
   /// Negating an integer, `-number`, is equivalent to subtracting
   /// it from zero, `0 - number`.
   ///
   /// (Both properties generally also hold for the other type,
   /// but with a few edge case exceptions).
   num operator -();

   /// 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 divider `this`.
   ///
   /// The result is an [int], as described by [int.remainder],
   /// if both this number and [other] is an integer,
   /// otherwise the result is a [double].
   num remainder(num other);

   /// Whether [other] is numerically smaller than this number.
   ///
   /// If either operand is the [double] NaN, the result is always false.
   bool operator <(num other);

   /// Whether [other] is numerically smaller than or equal to this number.
   ///
   /// If either operand is the [double] NaN, the result is always false.
   bool operator <=(num other);

   /// Whether [other] is numerically greater than this number.
   ///
   /// If either operand is the [double] NaN, the result is always false.
   bool operator >(num other);

   /// Whether [other] is numerically greater than or equal to this number.
   ///
   /// If either operand is the [double] NaN, the result is always false.
   bool operator >=(num other);

   /// Whether the number is the double Not-a-Number value.
   bool get isNaN;

   /// Whether if the number is negative.
   ///
   /// Negative numbers are those less than zero, and the double `-0.0`.
   bool get isNegative;

   /// Whether the number is positive infinity or negative infinity.
   bool get isInfinite;

   /// Whether the number is finite.
   ///
   /// The only non-finite numbers are NaN, positive infinity, and
   /// negative infinity. All integers are finite.
   bool get isFinite;

   /// 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.
   num abs();

   /// Negative one, zero or positive one depending on the sign and
   /// numerical value of the number.
   ///
   /// Returns minus one if the number is less than zero,
   /// plus one if the number is greater than zero,
   /// and zero if the number is equal to zero.
   ///
   /// Returns NaN if the number is the [double] NaN value.
   ///
   /// Returns a number of the same type as this number.
   /// For doubles, `-0.0.sign == -0.0`.
   ///
   /// The result satisfies:
   /// ```dart
   /// n == n.sign * n.abs()
   /// ```
   /// for all numbers `n` (except NaN, because NaN isn't `==` to itself).
   num get sign;

   /// 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`.
   ///
   /// The number must be finite (see [isFinite]).
   ///
   /// If the value is greater than the highest representable positive integer,
   /// the result is that highest positive integer.
   /// If the value is smaller than the highest representable negative integer,
   /// the result is that highest negative integer.
   int round();

   /// The greatest integer no greater than this number.
   ///
   /// Rounds fractional values towards negative infinity.
   ///
   /// The number must be finite (see [isFinite]).
   ///
   /// If the value is greater than the highest representable positive integer,
   /// the result is that highest positive integer.
   /// If the value is smaller than the highest representable negative integer,
   /// the result is that highest negative integer.
   int floor();

   /// The least integer no smaller than `this`.
   ///
   /// Rounds fractional values towards positive infinitiy.
   ///
   /// The number must be finite (see [isFinite]).
   ///
   /// If the value is greater than the highest representable positive integer,
   /// the result is that highest positive integer.
   /// If the value is smaller than the highest representable negative integer,
   /// the result is that highest negative integer.
   int ceil();

   /// The integer obtained by discarding any fractional digits from `this`.
   ///
   /// Rounds fractional values towards zero.
   ///
   /// The number must be finite (see [isFinite]).
   ///
   /// If the value is greater than the highest representable positive integer,
   /// the result is that highest positive integer.
   /// If the value is smaller than the highest representable negative integer,
   /// the result is that highest negative integer.
   int truncate();

   /// The double integer value closest to this value.
   ///
   /// 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 a
   /// non-finite double 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`.
   double roundToDouble();

   /// Returns the greatest double integer value no greater than `this`.
   ///
   /// If this is already an integer valued double, including `-0.0`, or it is a
   /// non-finite double 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`.
   double floorToDouble();

   /// Returns the least double integer value no smaller than `this`.
   ///
   /// If this is already an integer valued double, including `-0.0`, or it is a
   /// non-finite double 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`.
   double ceilToDouble();

   /// Returns the double integer value obtained by discarding any fractional
   /// digits from the double value of `this`.
   ///
   /// If this is already an integer valued double, including `-0.0`, or it is a
   /// non-finite double 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.
   double truncateToDouble();

   /// 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`.
   num clamp(num lowerLimit, num upperLimit);

   /// Truncates this [num] to an integer and returns the result as an [int].
   ///
   /// Equivalent to [truncate].
   int toInt();

   /// This number as a [double].
   ///
   /// If an integer number is not precisely representable as a [double],
   /// an approximation is returned.
   double toDouble();

   /// 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 then 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:
   /// ```dart
   /// 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
   /// ```
   String toStringAsFixed(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:
   /// ```dart
   /// 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
   /// ```
   String toStringAsExponential([int? fractionDigits]);

   /// 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:
   /// ```dart
   /// 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
   /// ```
   String toStringAsPrecision(int precision);

   /// The shortest string that correctly represent this number number.
   ///
   /// All [double]s in the range `10^-6` (inclusive) to `10^21` (exclusive)
   /// are converted to their decimal representation with at least one digit
   /// after the decimal point. For all other doubles,
   /// except for special values like `NaN` or `Infinity`, this method returns an
   /// exponential representation (see [toStringAsExponential]).
   ///
   /// Returns `"NaN"` for [double.nan], `"Infinity"` for [double.infinity], and
   /// `"-Infinity"` for [double.negativeInfinity].
   ///
   /// An [int] is converted to a decimal representation with no decimal point.
   ///
   /// Examples:
   /// ```dart
   /// (0.000001).toString();  // "0.000001"
   /// (0.0000001).toString(); // "1e-7"
   /// (111111111111111111111.0).toString();  // "111111111111111110000.0"
   /// (100000000000000000000.0).toString();  // "100000000000000000000.0"
   /// (1000000000000000000000.0).toString(); // "1e+21"
   /// (1111111111111111111111.0).toString(); // "1.1111111111111111e+21"
   /// 1.toString(); // "1"
   /// 111111111111111111111.toString();  // "111111111111111110000"
   /// 100000000000000000000.toString();  // "100000000000000000000"
   /// 1000000000000000000000.toString(); // "1000000000000000000000"
   /// 1111111111111111111111.toString(); // "1111111111111111111111"
   /// 1.234e5.toString();   // 123400
   /// 1234.5e6.toString();  // 1234500000
   /// 12.345e67.toString(); // 1.2345e+68
   /// ```
   /// Note: the conversion may round the output if the returned string
   /// is accurate enough to uniquely identify the input-number.
   /// For example the most precise representation of the [double] `9e59` equals
   /// `"899999999999999918767229449717619953810131273674690656206848"`, but
   /// this method returns the shorter (but still uniquely identifying) `"9e59"`.
   String toString();

   /// Parses a string containing a number literal into a number.
   ///
   /// The method first tries to read the [input] as integer (similar to
   /// [int.parse] without a radix).
   /// If that fails, it tries to parse the [input] as a double (similar to
   /// [double.parse]).
   /// If that fails, too, it invokes [onError] with [input], and the result
   /// of that invocation becomes the result of calling `parse`.
   ///
   /// If no [onError] is supplied, it defaults to a function that throws a
   /// [FormatException].
   ///
   /// For any number `n`, this function satisfies
   /// `identical(n, num.parse(n.toString()))` (except when `n` is a NaN `double`
   /// with a payload).
   ///
   /// The [onError] parameter is deprecated and will be removed.
   /// Instead of `num.parse(string, (string) { ... })`,
   /// you should use `num.tryParse(string) ?? (...)`.
   static num parse(String input, [@deprecated num onError(String input)?]) {
     num? result = tryParse(input);
     if (result != null) return result;
     if (onError == null) throw FormatException(input);
     return onError(input);
   }

   /// Parses a string containing a number literal into a number.
   ///
   /// Like [parse] except that this function returns `null` for invalid inputs
   /// instead of throwing.
   static num? tryParse(String input) {
     String source = input.trim();
     // TODO(lrn): Optimize to detect format and result type in one check.
     return int.tryParse(source) ?? double.tryParse(source);
   }
 }
	// Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
	// for details. All rights reserved. Use of this source code is governed by a
	// BSD-style license that can be found in the LICENSE file.

	part of dart.core;

	/// An integer or floating-point number.
	///
	/// It is a compile-time error for any type other than [int] or [double]
	/// to attempt to extend or implement `num`.
	abstract class num implements Comparable<num> {
	/// Test whether this value is numerically equal to `other`.
	///
	/// If both operands are [double]s, 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.
	bool operator ==(Object other);

	/// 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.
	int get hashCode;

	/// 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
	/// ```
	int compareTo(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].
	num 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].
	num operator -(num other);

	/// Multiplies this number by [other].
	///
	/// The result is an [int], as described by [int.*],
	/// if both this number and [other] is an integer,
	/// otherwise the result is a [double].
	num 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 stil 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] is an integer,
	/// otherwise the result is a [double].
	num operator %(num other);

	/// Divides this number by [other].
	double operator /(num other);

	/// Truncating division operator.
	///
	/// If either operand is a [double] then the result of the truncating division
	/// `a ~/ b` is equivalent to `(a / b).truncate().toInt()`.
	///
	/// If both operands are [int]s then `a ~/ b` performs the truncating
	/// integer division.
	int operator ~/(num other);

	/// The negation of this value.
	///
	/// The negation of a number is a number of the same kind
	/// (`int` or `double`) representing the negation of the
	/// numbers numerical value (the result of subtracting the
	/// number from zero), if that value exists.
	///
	/// Negating a double gives a number with same magnitude
	/// as the original value (`number.abs() == (-number).abs()`),
	/// and the opposite sign (`-(number.sign) == (-number).sign`).
	///
	/// Negating an integer, `-number`, is equivalent to subtracting
	/// it from zero, `0 - number`.
	///
	/// (Both properties generally also hold for the other type,
	/// but with a few edge case exceptions).
	num operator -();

	/// 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 divider `this`.
	///
	/// The result is an [int], as described by [int.remainder],
	/// if both this number and [other] is an integer,
	/// otherwise the result is a [double].
	num remainder(num other);

	/// Whether [other] is numerically smaller than this number.
	///
	/// If either operand is the [double] NaN, the result is always false.
	bool operator <(num other);

	/// Whether [other] is numerically smaller than or equal to this number.
	///
	/// If either operand is the [double] NaN, the result is always false.
	bool operator <=(num other);

	/// Whether [other] is numerically greater than this number.
	///
	/// If either operand is the [double] NaN, the result is always false.
	bool operator >(num other);

	/// Whether [other] is numerically greater than or equal to this number.
	///
	/// If either operand is the [double] NaN, the result is always false.
	bool operator >=(num other);

	/// Whether the number is the double Not-a-Number value.
	bool get isNaN;

	/// Whether if the number is negative.
	///
	/// Negative numbers are those less than zero, and the double `-0.0`.
	bool get isNegative;

	/// Whether the number is positive infinity or negative infinity.
	bool get isInfinite;

	/// Whether the number is finite.
	///
	/// The only non-finite numbers are NaN, positive infinity, and
	/// negative infinity. All integers are finite.
	bool get isFinite;

	/// 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.
	num abs();

	/// Negative one, zero or positive one depending on the sign and
	/// numerical value of the number.
	///
	/// Returns minus one if the number is less than zero,
	/// plus one if the number is greater than zero,
	/// and zero if the number is equal to zero.
	///
	/// Returns NaN if the number is the [double] NaN value.
	///
	/// Returns a number of the same type as this number.
	/// For doubles, `-0.0.sign == -0.0`.
	///
	/// The result satisfies:
	/// ```dart
	/// n == n.sign * n.abs()
	/// ```
	/// for all numbers `n` (except NaN, because NaN isn't `==` to itself).
	num get sign;

	/// 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`.
	///
	/// The number must be finite (see [isFinite]).
	///
	/// If the value is greater than the highest representable positive integer,
	/// the result is that highest positive integer.
	/// If the value is smaller than the highest representable negative integer,
	/// the result is that highest negative integer.
	int round();

	/// The greatest integer no greater than this number.
	///
	/// Rounds fractional values towards negative infinity.
	///
	/// The number must be finite (see [isFinite]).
	///
	/// If the value is greater than the highest representable positive integer,
	/// the result is that highest positive integer.
	/// If the value is smaller than the highest representable negative integer,
	/// the result is that highest negative integer.
	int floor();

	/// The least integer no smaller than `this`.
	///
	/// Rounds fractional values towards positive infinitiy.
	///
	/// The number must be finite (see [isFinite]).
	///
	/// If the value is greater than the highest representable positive integer,
	/// the result is that highest positive integer.
	/// If the value is smaller than the highest representable negative integer,
	/// the result is that highest negative integer.
	int ceil();

	/// The integer obtained by discarding any fractional digits from `this`.
	///
	/// Rounds fractional values towards zero.
	///
	/// The number must be finite (see [isFinite]).
	///
	/// If the value is greater than the highest representable positive integer,
	/// the result is that highest positive integer.
	/// If the value is smaller than the highest representable negative integer,
	/// the result is that highest negative integer.
	int truncate();

	/// The double integer value closest to this value.
	///
	/// 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 a
	/// non-finite double 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`.
	double roundToDouble();

	/// Returns the greatest double integer value no greater than `this`.
	///
	/// If this is already an integer valued double, including `-0.0`, or it is a
	/// non-finite double 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`.
	double floorToDouble();

	/// Returns the least double integer value no smaller than `this`.
	///
	/// If this is already an integer valued double, including `-0.0`, or it is a
	/// non-finite double 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`.
	double ceilToDouble();

	/// Returns the double integer value obtained by discarding any fractional
	/// digits from the double value of `this`.
	///
	/// If this is already an integer valued double, including `-0.0`, or it is a
	/// non-finite double 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.
	double truncateToDouble();

	/// 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`.
	num clamp(num lowerLimit, num upperLimit);

	/// Truncates this [num] to an integer and returns the result as an [int].
	///
	/// Equivalent to [truncate].
	int toInt();

	/// This number as a [double].
	///
	/// If an integer number is not precisely representable as a [double],
	/// an approximation is returned.
	double toDouble();

	/// 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 then 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:
	/// ```dart
	/// 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
	/// ```
	String toStringAsFixed(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:
	/// ```dart
	/// 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
	/// ```
	String toStringAsExponential([int? fractionDigits]);

	/// 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:
	/// ```dart
	/// 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
	/// ```
	String toStringAsPrecision(int precision);

	/// The shortest string that correctly represent this number number.
	///
	/// All [double]s in the range `10^-6` (inclusive) to `10^21` (exclusive)
	/// are converted to their decimal representation with at least one digit
	/// after the decimal point. For all other doubles,
	/// except for special values like `NaN` or `Infinity`, this method returns an
	/// exponential representation (see [toStringAsExponential]).
	///
	/// Returns `"NaN"` for [double.nan], `"Infinity"` for [double.infinity], and
	/// `"-Infinity"` for [double.negativeInfinity].
	///
	/// An [int] is converted to a decimal representation with no decimal point.
	///
	/// Examples:
	/// ```dart
	/// (0.000001).toString(); // "0.000001"
	/// (0.0000001).toString(); // "1e-7"
	/// (111111111111111111111.0).toString(); // "111111111111111110000.0"
	/// (100000000000000000000.0).toString(); // "100000000000000000000.0"
	/// (1000000000000000000000.0).toString(); // "1e+21"
	/// (1111111111111111111111.0).toString(); // "1.1111111111111111e+21"
	/// 1.toString(); // "1"
	/// 111111111111111111111.toString(); // "111111111111111110000"
	/// 100000000000000000000.toString(); // "100000000000000000000"
	/// 1000000000000000000000.toString(); // "1000000000000000000000"
	/// 1111111111111111111111.toString(); // "1111111111111111111111"
	/// 1.234e5.toString(); // 123400
	/// 1234.5e6.toString(); // 1234500000
	/// 12.345e67.toString(); // 1.2345e+68
	/// ```
	/// Note: the conversion may round the output if the returned string
	/// is accurate enough to uniquely identify the input-number.
	/// For example the most precise representation of the [double] `9e59` equals
	/// `"899999999999999918767229449717619953810131273674690656206848"`, but
	/// this method returns the shorter (but still uniquely identifying) `"9e59"`.
	String toString();

	/// Parses a string containing a number literal into a number.
	///
	/// The method first tries to read the [input] as integer (similar to
	/// [int.parse] without a radix).
	/// If that fails, it tries to parse the [input] as a double (similar to
	/// [double.parse]).
	/// If that fails, too, it invokes [onError] with [input], and the result
	/// of that invocation becomes the result of calling `parse`.
	///
	/// If no [onError] is supplied, it defaults to a function that throws a
	/// [FormatException].
	///
	/// For any number `n`, this function satisfies
	/// `identical(n, num.parse(n.toString()))` (except when `n` is a NaN `double`
	/// with a payload).
	///
	/// The [onError] parameter is deprecated and will be removed.
	/// Instead of `num.parse(string, (string) { ... })`,
	/// you should use `num.tryParse(string) ?? (...)`.
	static num parse(String input, [@deprecated num onError(String input)?]) {
	num? result = tryParse(input);
	if (result != null) return result;
	if (onError == null) throw FormatException(input);
	return onError(input);
	}

	/// Parses a string containing a number literal into a number.
	///
	/// Like [parse] except that this function returns `null` for invalid inputs
	/// instead of throwing.
	static num? tryParse(String input) {
	String source = input.trim();
	// TODO(lrn): Optimize to detect format and result type in one check.
	return int.tryParse(source) ?? double.tryParse(source);
	}
	}