sdk/lib/math/math.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.

 /// Mathematical constants and functions, plus a random number generator.
 ///
 /// To use this library in your code:
 /// ```dart
 /// import 'dart:math';
 /// ```
 ///
 /// ## Random
 /// [Random] is a generator of [bool], [int] or [double] values.
 /// ```dart
 /// var intValue = Random().nextInt(10); // Value is >= 0 and < 10.
 /// var doubleValue = Random().nextDouble(); // Value is >= 0.0 and < 1.0.
 /// var boolValue = Random().nextBool(); // true or false, with equal chance.
 /// ```
 ///
 /// ## Point
 /// [Point] is a utility class for representing two-dimensional positions.
 /// ```dart
 /// var leftTop = const Point(0, 0);
 /// var rightBottom = const Point(200, 400);
 /// ```
 ///
 /// ## Rectangle
 /// [Rectangle] is a class for representing two-dimensional axis-aligned
 /// rectangles whose properties are immutable.
 ///
 /// Create a rectangle spanned by the points.
 /// ```dart
 /// var leftTop = const Point(20, 50);
 /// var rightBottom = const Point(300, 600);
 /// var rectangle = Rectangle.fromPoints(leftTop, rightBottom);
 /// print(rectangle.left); // 20
 /// print(rectangle.top); // 50
 /// print(rectangle.right); // 300
 /// print(rectangle.bottom); // 600
 /// ```
 ///
 /// Create a rectangle spanned by `(left, top)` and
 /// `(left+width, top+height)`.
 /// ```dart
 /// var rectangle = const Rectangle(20, 50, 300, 600);
 /// print(rectangle.left); // 20
 /// print(rectangle.top); // 50
 /// print(rectangle.right); // 320
 /// print(rectangle.bottom); // 650
 /// ```
 ///
 /// ## MutableRectangle
 /// [MutableRectangle] is a class for representing two-dimensional axis-aligned
 /// rectangles with mutable properties.
 ///
 /// Create a mutable rectangle spanned by `(left, top)` and
 /// `(left+width, top+height)`.
 /// ```dart
 /// var rectangle = MutableRectangle(20, 50, 300, 600);
 /// print(rectangle); // Rectangle (20, 50) 300 x 600
 /// print(rectangle.left); // 20
 /// print(rectangle.top); // 50
 /// print(rectangle.right); // 320
 /// print(rectangle.bottom); // 650
 ///
 /// // Change rectangle width and height.
 /// rectangle.width = 200;
 /// rectangle.height = 100;
 /// print(rectangle); // Rectangle (20, 50) 200 x 100
 /// print(rectangle.left); // 20
 /// print(rectangle.top); // 50
 /// print(rectangle.right); // 220
 /// print(rectangle.bottom); // 150
 /// ```
 ///
 /// {@category Core}
 library dart.math;

 import "dart:_internal" show SystemHash;

 part "point.dart";
 part "random.dart";
 part "rectangle.dart";

 /// Base of the natural logarithms.
 ///
 /// Typically written as "e".
 const double e = 2.718281828459045;

 /// Natural logarithm of 10.
 ///
 /// The natural logarithm of 10 is the number such that `pow(E, LN10) == 10`.
 /// This value is not exact, but it is the closest representable double to the
 /// exact mathematical value.
 const double ln10 = 2.302585092994046;

 /// Natural logarithm of 2.
 ///
 /// The natural logarithm of 2 is the number such that `pow(E, LN2) == 2`.
 /// This value is not exact, but it is the closest representable double to the
 /// exact mathematical value.
 const double ln2 = 0.6931471805599453;

 /// Base-2 logarithm of [e].
 const double log2e = 1.4426950408889634;

 /// Base-10 logarithm of [e].
 const double log10e = 0.4342944819032518;

 /// The PI constant.
 const double pi = 3.1415926535897932;

 /// Square root of 1/2.
 const double sqrt1_2 = 0.7071067811865476;

 /// Square root of 2.
 const double sqrt2 = 1.4142135623730951;

 /// Returns the lesser of two numbers.
 ///
 /// Returns NaN if either argument is NaN.
 /// The lesser of `-0.0` and `0.0` is `-0.0`.
 /// If the arguments are otherwise equal (including int and doubles with the
 /// same mathematical value) then it is unspecified which of the two arguments
 /// is returned.
 external T min<T extends num>(T a, T b);

 /// Returns the larger of two numbers.
 ///
 /// Returns NaN if either argument is NaN.
 /// The larger of `-0.0` and `0.0` is `0.0`. If the arguments are
 /// otherwise equal (including int and doubles with the same mathematical value)
 /// then it is unspecified which of the two arguments is returned.
 external T max<T extends num>(T a, T b);

 /// A variant of [atan].
 ///
 /// Converts both arguments to [double]s.
 ///
 /// Returns the angle in radians between the positive x-axis
 /// and the vector ([b],[a]).
 /// The result is in the range -PI..PI.
 ///
 /// If [b] is positive, this is the same as `atan(a/b)`.
 ///
 /// The result is negative when [a] is negative (including when [a] is the
 /// double -0.0).
 ///
 /// If [a] is equal to zero, the vector ([b],[a]) is considered parallel to
 /// the x-axis, even if [b] is also equal to zero. The sign of [b] determines
 /// the direction of the vector along the x-axis.
 ///
 /// Returns NaN if either argument is NaN.
 external double atan2(num a, num b);

 /// Returns [x] to the power of [exponent].
 ///
 /// If [x] is an [int] and [exponent] is a non-negative [int], the result is
 /// an [int], otherwise both arguments are converted to doubles first, and the
 /// result is a [double].
 ///
 /// For integers, the power is always equal to the mathematical result of `x` to
 /// the power `exponent`, only limited by the available memory.
 ///
 /// For doubles, `pow(x, y)` handles edge cases as follows:
 ///
 /// - if `y` is zero (0.0 or -0.0), the result is always 1.0.
 /// - if `x` is 1.0, the result is always 1.0.
 /// - otherwise, if either `x` or `y` is NaN, then the result is NaN.
 /// - if `x` is negative (but not -0.0) and `y` is a finite non-integer, the
 ///   result is NaN.
 /// - if `x` is Infinity and `y` is negative, the result is 0.0.
 /// - if `x` is Infinity and `y` is positive, the result is Infinity.
 /// - if `x` is 0.0 and `y` is negative, the result is Infinity.
 /// - if `x` is 0.0 and `y` is positive, the result is 0.0.
 /// - if `x` is -Infinity or -0.0 and `y` is an odd integer, then the result is
 ///   `-pow(-x ,y)`.
 /// - if `x` is -Infinity or -0.0 and `y` is not an odd integer, then the result
 ///   is the same as `pow(-x , y)`.
 /// - if `y` is Infinity and the absolute value of `x` is less than 1, the
 ///   result is 0.0.
 /// - if `y` is Infinity and `x` is -1, the result is 1.0.
 /// - if `y` is Infinity and the absolute value of `x` is greater than 1,
 ///   the result is Infinity.
 /// - if `y` is -Infinity, the result is `1/pow(x, Infinity)`.
 ///
 /// This corresponds to the `pow` function defined in the IEEE Standard
 /// 754-2008.
 ///
 /// Notice that the result may overflow. If integers are represented as 64-bit
 /// numbers, an integer result may be truncated, and a double result may
 /// overflow to positive or negative [double.infinity].
 external num pow(num x, num exponent);

 /// Converts [radians] to a [double] and returns the sine of the value.
 ///
 /// If [radians] is not a finite number, the result is NaN.
 external double sin(num radians);

 /// Converts [radians] to a [double] and returns the cosine of the value.
 ///
 /// If [radians] is not a finite number, the result is NaN.
 external double cos(num radians);

 /// Converts [radians] to a [double] and returns the tangent of the value.
 ///
 /// The tangent function is equivalent to `sin(radians)/cos(radians)` and may be
 /// infinite (positive or negative) when `cos(radians)` is equal to zero.
 /// If [radians] is not a finite number, the result is NaN.
 external double tan(num radians);

 /// Converts [x] to a [double] and returns its arc cosine in radians.
 ///
 /// Returns a value in the range 0..PI, or NaN if [x] is outside
 /// the range -1..1.
 external double acos(num x);

 /// Converts [x] to a [double] and returns its arc sine in radians.
 ///
 /// Returns a value in the range -PI/2..PI/2, or NaN if [x] is outside
 /// the range -1..1.
 external double asin(num x);

 /// Converts [x] to a [double] and returns its arc tangent in radians.
 ///
 /// Returns a value in the range -PI/2..PI/2, or NaN if [x] is NaN.
 external double atan(num x);

 /// Converts [x] to a [double] and returns the positive square root of the
 /// value.
 ///
 /// Returns -0.0 if [x] is -0.0, and NaN if [x] is otherwise negative or NaN.
 /// ```dart
 /// var result = sqrt(9.3);
 /// print(result); // 3.0495901363953815
 /// result = sqrt(2);
 /// print(result); // 1.4142135623730951
 /// result = sqrt(0);
 /// print(result); // 0.0
 /// result = sqrt(-2.2);
 /// print(result); // NaN
 /// ```
 external double sqrt(num x);

 /// Converts [x] to a [double] and returns the natural exponent, [e],
 /// to the power [x].
 ///
 /// Returns NaN if [x] is NaN.
 external double exp(num x);

 /// Converts [x] to a [double] and returns the natural logarithm of the value.
 ///
 /// Returns negative infinity if [x] is equal to zero.
 /// Returns NaN if [x] is NaN or less than zero.
 external double log(num x);
	// 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.

	/// Mathematical constants and functions, plus a random number generator.
	///
	/// To use this library in your code:
	/// ```dart
	/// import 'dart:math';
	/// ```
	///
	/// ## Random
	/// [Random] is a generator of [bool], [int] or [double] values.
	/// ```dart
	/// var intValue = Random().nextInt(10); // Value is >= 0 and < 10.
	/// var doubleValue = Random().nextDouble(); // Value is >= 0.0 and < 1.0.
	/// var boolValue = Random().nextBool(); // true or false, with equal chance.
	/// ```
	///
	/// ## Point
	/// [Point] is a utility class for representing two-dimensional positions.
	/// ```dart
	/// var leftTop = const Point(0, 0);
	/// var rightBottom = const Point(200, 400);
	/// ```
	///
	/// ## Rectangle
	/// [Rectangle] is a class for representing two-dimensional axis-aligned
	/// rectangles whose properties are immutable.
	///
	/// Create a rectangle spanned by the points.
	/// ```dart
	/// var leftTop = const Point(20, 50);
	/// var rightBottom = const Point(300, 600);
	/// var rectangle = Rectangle.fromPoints(leftTop, rightBottom);
	/// print(rectangle.left); // 20
	/// print(rectangle.top); // 50
	/// print(rectangle.right); // 300
	/// print(rectangle.bottom); // 600
	/// ```
	///
	/// Create a rectangle spanned by `(left, top)` and
	/// `(left+width, top+height)`.
	/// ```dart
	/// var rectangle = const Rectangle(20, 50, 300, 600);
	/// print(rectangle.left); // 20
	/// print(rectangle.top); // 50
	/// print(rectangle.right); // 320
	/// print(rectangle.bottom); // 650
	/// ```
	///
	/// ## MutableRectangle
	/// [MutableRectangle] is a class for representing two-dimensional axis-aligned
	/// rectangles with mutable properties.
	///
	/// Create a mutable rectangle spanned by `(left, top)` and
	/// `(left+width, top+height)`.
	/// ```dart
	/// var rectangle = MutableRectangle(20, 50, 300, 600);
	/// print(rectangle); // Rectangle (20, 50) 300 x 600
	/// print(rectangle.left); // 20
	/// print(rectangle.top); // 50
	/// print(rectangle.right); // 320
	/// print(rectangle.bottom); // 650
	///
	/// // Change rectangle width and height.
	/// rectangle.width = 200;
	/// rectangle.height = 100;
	/// print(rectangle); // Rectangle (20, 50) 200 x 100
	/// print(rectangle.left); // 20
	/// print(rectangle.top); // 50
	/// print(rectangle.right); // 220
	/// print(rectangle.bottom); // 150
	/// ```
	///
	/// {@category Core}
	library dart.math;

	import "dart:_internal" show SystemHash;

	part "point.dart";
	part "random.dart";
	part "rectangle.dart";

	/// Base of the natural logarithms.
	///
	/// Typically written as "e".
	const double e = 2.718281828459045;

	/// Natural logarithm of 10.
	///
	/// The natural logarithm of 10 is the number such that `pow(E, LN10) == 10`.
	/// This value is not exact, but it is the closest representable double to the
	/// exact mathematical value.
	const double ln10 = 2.302585092994046;

	/// Natural logarithm of 2.
	///
	/// The natural logarithm of 2 is the number such that `pow(E, LN2) == 2`.
	/// This value is not exact, but it is the closest representable double to the
	/// exact mathematical value.
	const double ln2 = 0.6931471805599453;

	/// Base-2 logarithm of [e].
	const double log2e = 1.4426950408889634;

	/// Base-10 logarithm of [e].
	const double log10e = 0.4342944819032518;

	/// The PI constant.
	const double pi = 3.1415926535897932;

	/// Square root of 1/2.
	const double sqrt1_2 = 0.7071067811865476;

	/// Square root of 2.
	const double sqrt2 = 1.4142135623730951;

	/// Returns the lesser of two numbers.
	///
	/// Returns NaN if either argument is NaN.
	/// The lesser of `-0.0` and `0.0` is `-0.0`.
	/// If the arguments are otherwise equal (including int and doubles with the
	/// same mathematical value) then it is unspecified which of the two arguments
	/// is returned.
	external T min<T extends num>(T a, T b);

	/// Returns the larger of two numbers.
	///
	/// Returns NaN if either argument is NaN.
	/// The larger of `-0.0` and `0.0` is `0.0`. If the arguments are
	/// otherwise equal (including int and doubles with the same mathematical value)
	/// then it is unspecified which of the two arguments is returned.
	external T max<T extends num>(T a, T b);

	/// A variant of [atan].
	///
	/// Converts both arguments to [double]s.
	///
	/// Returns the angle in radians between the positive x-axis
	/// and the vector ([b],[a]).
	/// The result is in the range -PI..PI.
	///
	/// If [b] is positive, this is the same as `atan(a/b)`.
	///
	/// The result is negative when [a] is negative (including when [a] is the
	/// double -0.0).
	///
	/// If [a] is equal to zero, the vector ([b],[a]) is considered parallel to
	/// the x-axis, even if [b] is also equal to zero. The sign of [b] determines
	/// the direction of the vector along the x-axis.
	///
	/// Returns NaN if either argument is NaN.
	external double atan2(num a, num b);

	/// Returns [x] to the power of [exponent].
	///
	/// If [x] is an [int] and [exponent] is a non-negative [int], the result is
	/// an [int], otherwise both arguments are converted to doubles first, and the
	/// result is a [double].
	///
	/// For integers, the power is always equal to the mathematical result of `x` to
	/// the power `exponent`, only limited by the available memory.
	///
	/// For doubles, `pow(x, y)` handles edge cases as follows:
	///
	/// - if `y` is zero (0.0 or -0.0), the result is always 1.0.
	/// - if `x` is 1.0, the result is always 1.0.
	/// - otherwise, if either `x` or `y` is NaN, then the result is NaN.
	/// - if `x` is negative (but not -0.0) and `y` is a finite non-integer, the
	/// result is NaN.
	/// - if `x` is Infinity and `y` is negative, the result is 0.0.
	/// - if `x` is Infinity and `y` is positive, the result is Infinity.
	/// - if `x` is 0.0 and `y` is negative, the result is Infinity.
	/// - if `x` is 0.0 and `y` is positive, the result is 0.0.
	/// - if `x` is -Infinity or -0.0 and `y` is an odd integer, then the result is
	/// `-pow(-x ,y)`.
	/// - if `x` is -Infinity or -0.0 and `y` is not an odd integer, then the result
	/// is the same as `pow(-x , y)`.
	/// - if `y` is Infinity and the absolute value of `x` is less than 1, the
	/// result is 0.0.
	/// - if `y` is Infinity and `x` is -1, the result is 1.0.
	/// - if `y` is Infinity and the absolute value of `x` is greater than 1,
	/// the result is Infinity.
	/// - if `y` is -Infinity, the result is `1/pow(x, Infinity)`.
	///
	/// This corresponds to the `pow` function defined in the IEEE Standard
	/// 754-2008.
	///
	/// Notice that the result may overflow. If integers are represented as 64-bit
	/// numbers, an integer result may be truncated, and a double result may
	/// overflow to positive or negative [double.infinity].
	external num pow(num x, num exponent);

	/// Converts [radians] to a [double] and returns the sine of the value.
	///
	/// If [radians] is not a finite number, the result is NaN.
	external double sin(num radians);

	/// Converts [radians] to a [double] and returns the cosine of the value.
	///
	/// If [radians] is not a finite number, the result is NaN.
	external double cos(num radians);

	/// Converts [radians] to a [double] and returns the tangent of the value.
	///
	/// The tangent function is equivalent to `sin(radians)/cos(radians)` and may be
	/// infinite (positive or negative) when `cos(radians)` is equal to zero.
	/// If [radians] is not a finite number, the result is NaN.
	external double tan(num radians);

	/// Converts [x] to a [double] and returns its arc cosine in radians.
	///
	/// Returns a value in the range 0..PI, or NaN if [x] is outside
	/// the range -1..1.
	external double acos(num x);

	/// Converts [x] to a [double] and returns its arc sine in radians.
	///
	/// Returns a value in the range -PI/2..PI/2, or NaN if [x] is outside
	/// the range -1..1.
	external double asin(num x);

	/// Converts [x] to a [double] and returns its arc tangent in radians.
	///
	/// Returns a value in the range -PI/2..PI/2, or NaN if [x] is NaN.
	external double atan(num x);

	/// Converts [x] to a [double] and returns the positive square root of the
	/// value.
	///
	/// Returns -0.0 if [x] is -0.0, and NaN if [x] is otherwise negative or NaN.
	/// ```dart
	/// var result = sqrt(9.3);
	/// print(result); // 3.0495901363953815
	/// result = sqrt(2);
	/// print(result); // 1.4142135623730951
	/// result = sqrt(0);
	/// print(result); // 0.0
	/// result = sqrt(-2.2);
	/// print(result); // NaN
	/// ```
	external double sqrt(num x);

	/// Converts [x] to a [double] and returns the natural exponent, [e],
	/// to the power [x].
	///
	/// Returns NaN if [x] is NaN.
	external double exp(num x);

	/// Converts [x] to a [double] and returns the natural logarithm of the value.
	///
	/// Returns negative infinity if [x] is equal to zero.
	/// Returns NaN if [x] is NaN or less than zero.
	external double log(num x);