| // 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.0 and < 1.0. |
| /// 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); |