blob: ffe8325cc4b86b392b545aff9cab617b5d742e42 [file] [log] [blame]
// 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:
*
* import 'dart:math';
*/
library dart.math;
import "dart:typed_data";
part "jenkins_smi_hash.dart";
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.
*/
const double LN10 = 2.302585092994046;
/**
* Natural logarithm of 2.
*/
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.
*/
T min<T extends num>(T a, T b) {
// These partially redundant type checks improve code quality for dart2js.
// Most of the improvement is at call sites from the inferred non-null num
// return type.
if (a is! num) throw new ArgumentError(a);
if (b is! num) throw new ArgumentError(b);
if (a > b) return b;
if (a < b) return a;
if (b is double) {
// Special case for NaN and -0.0. If one argument is NaN return NaN.
// [min] must also distinguish between -0.0 and 0.0.
if (a is double) {
if (a == 0.0) {
// a is either 0.0 or -0.0. b is either 0.0, -0.0 or NaN.
// The following returns -0.0 if either a or b is -0.0, and it
// returns NaN if b is NaN.
return (a + b) * a * b;
}
}
// Check for NaN and b == -0.0.
if (a == 0 && b.isNegative || b.isNaN) return b;
return a;
}
return a;
}
/**
* 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.
*/
T max<T extends num>(T a, T b) {
// These partially redundant type checks improve code quality for dart2js.
// Most of the improvement is at call sites from the inferred non-null num
// return type.
if (a is! num) throw new ArgumentError(a);
if (b is! num) throw new ArgumentError(b);
if (a > b) return a;
if (a < b) return b;
if (b is double) {
// Special case for NaN and -0.0. If one argument is NaN return NaN.
// [max] must also distinguish between -0.0 and 0.0.
if (a is double) {
if (a == 0.0) {
// a is either 0.0 or -0.0. b is either 0.0, -0.0, or NaN.
// The following returns 0.0 if either a or b is 0.0, and it
// returns NaN if b is NaN.
return a + b;
}
}
// Check for NaN.
if (b.isNaN) return b;
return a;
}
// max(-0.0, 0) must return 0.
if (b == 0 && a.isNegative) return b;
return a;
}
/**
* A variant of [atan].
*
* Converts both arguments to doubles.
*
* Returns the angle between the positive x-axis and the vector ([b],[a]).
* The result, in radians, is in the range -PI..PI.
*
* If [b] is positive, this is the same as `atan(b/a)`.
*
* 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.
*/
double atan2(num a, num b) => _atan2(a.toDouble(), b.toDouble());
/**
* 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 an [int] result cannot overflow, but a [double] result might
* be [double.INFINITY].
*/
num pow(num x, num exponent) {
if ((x is int) && (exponent is int) && (exponent >= 0)) {
return _intPow(x, exponent);
}
return _doublePow(x.toDouble(), exponent.toDouble());
}
/**
* Converts [x] to a double and returns the sine of the value.
*
* If [x] is not a finite number, the result is NaN.
*/
double sin(num x) => _sin(x.toDouble());
/**
* Converts [x] to a double and returns the cosine of the value.
*
* If [x] is not a finite number, the result is NaN.
*/
double cos(num x) => _cos(x.toDouble());
/**
* Converts [x] to a double and returns the tangent of the value.
*
* The tangent function is equivalent to `sin(x)/cos(x)` and may be
* infinite (positive or negative) when `cos(x)` is equal to zero.
* If [x] is not a finite number, the result is NaN.
*/
double tan(num x) => _tan(x.toDouble());
/**
* Converts [x] to a double and returns the arc cosine of the value.
*
* Returns a value in the range 0..PI, or NaN if [x] is outside
* the range -1..1.
*/
double acos(num x) => _acos(x.toDouble());
/**
* Converts [x] to a double and returns the arc sine of the value.
*
* Returns a value in the range -PI/2..PI/2, or NaN if [x] is outside
* the range -1..1.
*/
double asin(num x) => _asin(x.toDouble());
/**
* Converts [x] to a double and returns the arc tangent of the value.
*
* Returns a value in the range -PI/2..PI/2, or NaN if [x] is NaN.
*/
double atan(num x) => _atan(x.toDouble());
/**
* 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.
*/
double sqrt(num x) => _sqrt(x.toDouble());
/**
* Converts [x] to a double and returns the natural exponent, [E],
* to the power [x].
*
* Returns NaN if [x] is NaN.
*/
double exp(num x) => _exp(x.toDouble());
/**
* 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.
*/
double log(num x) => _log(x.toDouble());
double _doublePow(double base, double exponent) {
if (exponent == 0.0) {
return 1.0; // ECMA-262 15.8.2.13
}
// Speed up simple cases.
if (exponent == 1.0) return base;
if (exponent == 2.0) return base * base;
if (exponent == 3.0) return base * base * base;
if (base == 1.0) return 1.0;
if (base.isNaN || exponent.isNaN) {
return double.NAN;
}
if ((base != -double.INFINITY) && (exponent == 0.5)) {
if (base == 0.0) {
return 0.0;
}
return sqrt(base);
}
return _pow(base.toDouble(), exponent.toDouble());
}
double _pow(double base, double exponent) native "Math_doublePow";
int _intPow(int base, int exponent) {
// Exponentiation by squaring.
int result = 1;
while (exponent != 0) {
if ((exponent & 1) == 1) {
result *= base;
}
exponent >>= 1;
// Skip unnecessary operation (can overflow to Mint or Bigint).
if (exponent != 0) {
base *= base;
}
}
return result;
}
double _atan2(double a, double b) native "Math_atan2";
double _sin(double x) native "Math_sin";
double _cos(double x) native "Math_cos";
double _tan(double x) native "Math_tan";
double _acos(double x) native "Math_acos";
double _asin(double x) native "Math_asin";
double _atan(double x) native "Math_atan";
double _sqrt(double x) native "Math_sqrt";
double _exp(double x) native "Math_exp";
double _log(double x) native "Math_log";
class _Random implements Random {
// Internal state of the random number generator.
final Uint32List _state;
static const _kSTATE_LO = 0;
static const _kSTATE_HI = 1; // Unused in Dart code.
_Random._withState(this._state);
// The algorithm used here is Multiply with Carry (MWC) with a Base b = 2^32.
// http://en.wikipedia.org/wiki/Multiply-with-carry
// The constant A is selected from "Numerical Recipes 3rd Edition" p.348 B1.
// Implements:
// var state =
// ((_A * (_state[_kSTATE_LO])) + _state[_kSTATE_HI]) & ((1 << 64) - 1);
// _state[_kSTATE_LO] = state & ((1 << 32) - 1);
// _state[_kSTATE_HI] = state >> 32;
// This is a native to prevent 64-bit operations in Dart, which
// fail with --throw_on_javascript_int_overflow.
// TODO(regis): Implement in Dart and remove Random_nextState in math.cc.
void _nextState() native "Random_nextState";
int nextInt(int max) {
const limit = 0x3FFFFFFF;
if ((max <= 0) || ((max > limit) && (max > _POW2_32))) {
throw new RangeError.range(
max, 1, _POW2_32, "max", "Must be positive and <= 2^32");
}
if ((max & -max) == max) {
// Fast case for powers of two.
_nextState();
return _state[_kSTATE_LO] & (max - 1);
}
int rnd32;
int result;
do {
_nextState();
rnd32 = _state[_kSTATE_LO];
result = rnd32 % max;
} while ((rnd32 - result + max) > _POW2_32);
return result;
}
double nextDouble() {
return ((nextInt(1 << 26) * _POW2_27_D) + nextInt(1 << 27)) / _POW2_53_D;
}
bool nextBool() {
return nextInt(2) == 0;
}
// Constants used by the algorithm.
static const _POW2_32 = 1 << 32;
static const _POW2_53_D = 1.0 * (1 << 53);
static const _POW2_27_D = 1.0 * (1 << 27);
static const _A = 0xffffda61;
// Use a singleton Random object to get a new seed if no seed was passed.
static var _prng = new _Random._withState(_initialSeed());
// This is a native to prevent 64-bit operations in Dart, which
// fail with --throw_on_javascript_int_overflow.
// TODO(regis): Implement here in Dart and remove native in math.cc.
static Uint32List _setupSeed(int seed) native "Random_setupSeed";
// Get a seed from the VM's random number provider.
static Uint32List _initialSeed() native "Random_initialSeed";
static int _nextSeed() {
// Trigger the PRNG once to change the internal state.
_prng._nextState();
return _prng._state[_kSTATE_LO];
}
}
class _SecureRandom implements Random {
_SecureRandom() {
// Throw early in constructor if entropy source is not hooked up.
_getBytes(1);
}
// Return count bytes of entropy as a positive integer; count <= 8.
static int _getBytes(int count) native "SecureRandom_getBytes";
int nextInt(int max) {
RangeError.checkValueInInterval(
max, 1, _POW2_32, "max", "Must be positive and <= 2^32");
final byteCount = ((max - 1).bitLength + 7) >> 3;
if (byteCount == 0) {
return 0; // Not random if max == 1.
}
var rnd;
var result;
do {
rnd = _getBytes(byteCount);
result = rnd % max;
} while ((rnd - result + max) > (1 << (byteCount << 3)));
return result;
}
double nextDouble() {
return (_getBytes(7) >> 3) / _POW2_53_D;
}
bool nextBool() {
return _getBytes(1).isEven;
}
// Constants used by the algorithm.
static const _POW2_32 = 1 << 32;
static const _POW2_53_D = 1.0 * (1 << 53);
}