21.3 The Math Object

The Math object:

  • is %Math%.
  • is the initial value of the "Math" property of the global object.
  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is not a function object.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.
Note

In this specification, the phrase “the Number value for x” has a technical meaning defined in 6.1.6.1.

21.3.1 Value Properties of the Math Object

21.3.1.1 Math.E

The Number value for e, the base of the natural logarithms, which is approximately 2.7182818284590452354.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

21.3.1.2 Math.LN10

The Number value for the natural logarithm of 10, which is approximately 2.302585092994046.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

21.3.1.3 Math.LN2

The Number value for the natural logarithm of 2, which is approximately 0.6931471805599453.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

21.3.1.4 Math.LOG10E

The Number value for the base-10 logarithm of e, the base of the natural logarithms; this value is approximately 0.4342944819032518.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

Note

The value of Math.LOG10E is approximately the reciprocal of the value of Math.LN10.

21.3.1.5 Math.LOG2E

The Number value for the base-2 logarithm of e, the base of the natural logarithms; this value is approximately 1.4426950408889634.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

Note

The value of Math.LOG2E is approximately the reciprocal of the value of Math.LN2.

21.3.1.6 Math.PI

The Number value for π, the ratio of the circumference of a circle to its diameter, which is approximately 3.1415926535897932.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

21.3.1.7 Math.SQRT1_2

The Number value for the square root of ½, which is approximately 0.7071067811865476.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

Note

The value of Math.SQRT1_2 is approximately the reciprocal of the value of Math.SQRT2.

21.3.1.8 Math.SQRT2

The Number value for the square root of 2, which is approximately 1.4142135623730951.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

21.3.1.9 Math [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Math".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

21.3.2 Function Properties of the Math Object

Note

The behaviour of the functions acos, acosh, asin, asinh, atan, atanh, atan2, cbrt, cos, cosh, exp, expm1, hypot, log,log1p, log2, log10, pow, random, sin, sinh, sqrt, tan, and tanh is not precisely specified here except to require specific results for certain argument values that represent boundary cases of interest. For other argument values, these functions are intended to compute approximations to the results of familiar mathematical functions, but some latitude is allowed in the choice of approximation algorithms. The general intent is that an implementer should be able to use the same mathematical library for ECMAScript on a given hardware platform that is available to C programmers on that platform.

Although the choice of algorithms is left to the implementation, it is recommended (but not specified by this standard) that implementations use the approximation algorithms for IEEE 754-2019 arithmetic contained in fdlibm, the freely distributable mathematical library from Sun Microsystems (http://www.netlib.org/fdlibm).

21.3.2.1 Math.abs ( x )

Returns the absolute value of x; the result has the same magnitude as x but has positive sign.

When the Math.abs method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, return NaN.
  3. If n is -0𝔽, return +0𝔽.
  4. If n is -∞𝔽, return +∞𝔽.
  5. If n < +0𝔽, return -n.
  6. Return n.

21.3.2.2 Math.acos ( x )

Returns the inverse cosine of x. The result is expressed in radians and ranges from +0𝔽 to 𝔽(π), inclusive.

When the Math.acos method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n > 1𝔽, or n < -1𝔽, return NaN.
  3. If n is 1𝔽, return +0𝔽.
  4. Return an implementation-approximated value representing the result of the inverse cosine of (n).

21.3.2.3 Math.acosh ( x )

Returns the inverse hyperbolic cosine of x.

When the Math.acosh method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n < 1𝔽, return NaN.
  5. Return an implementation-approximated value representing the result of the inverse hyperbolic cosine of (n).

21.3.2.4 Math.asin ( x )

Returns the inverse sine of x. The result is expressed in radians and ranges from 𝔽(-π / 2) to 𝔽(π / 2), inclusive.

When the Math.asin method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n > 1𝔽 or n < -1𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the inverse sine of (n).

21.3.2.5 Math.asinh ( x )

Returns the inverse hyperbolic sine of x.

When the Math.asinh method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. Return an implementation-approximated value representing the result of the inverse hyperbolic sine of (n).

21.3.2.6 Math.atan ( x )

Returns the inverse tangent of x. The result is expressed in radians and ranges from 𝔽(-π / 2) to 𝔽(π / 2), inclusive.

When the Math.atan method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n is +∞𝔽, return an implementation-approximated value representing π / 2.
  4. If n is -∞𝔽, return an implementation-approximated value representing -π / 2.
  5. Return an implementation-approximated value representing the result of the inverse tangent of (n).

21.3.2.7 Math.atanh ( x )

Returns the inverse hyperbolic tangent of x.

When the Math.atanh method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n > 1𝔽 or n < -1𝔽, return NaN.
  4. If n is 1𝔽, return +∞𝔽.
  5. If n is -1𝔽, return -∞𝔽.
  6. Return an implementation-approximated value representing the result of the inverse hyperbolic tangent of (n).

21.3.2.8 Math.atan2 ( y, x )

Returns the inverse tangent of the quotient y / x of the arguments y and x, where the signs of y and x are used to determine the quadrant of the result. Note that it is intentional and traditional for the two-argument inverse tangent function that the argument named y be first and the argument named x be second. The result is expressed in radians and ranges from -π to +π, inclusive.

When the Math.atan2 method is called with arguments y and x, the following steps are taken:

  1. Let ny be ? ToNumber(y).
  2. Let nx be ? ToNumber(x).
  3. If ny is NaN or nx is NaN, return NaN.
  4. If ny is +∞𝔽, then
    1. If nx is +∞𝔽, return an implementation-approximated value representing π / 4.
    2. If nx is -∞𝔽, return an implementation-approximated value representing 3π / 4.
    3. Return an implementation-approximated value representing π / 2.
  5. If ny is -∞𝔽, then
    1. If nx is +∞𝔽, return an implementation-approximated value representing -π / 4.
    2. If nx is -∞𝔽, return an implementation-approximated value representing -3π / 4.
    3. Return an implementation-approximated value representing -π / 2.
  6. If ny is +0𝔽, then
    1. If nx > +0𝔽 or nx is +0𝔽, return +0𝔽.
    2. Return an implementation-approximated value representing π.
  7. If ny is -0𝔽, then
    1. If nx > +0𝔽 or nx is +0𝔽, return -0𝔽.
    2. Return an implementation-approximated value representing -π.
  8. Assert: ny is finite and is neither +0𝔽 nor -0𝔽.
  9. If ny > +0𝔽, then
    1. If nx is +∞𝔽, return +0𝔽.
    2. If nx is -∞𝔽, return an implementation-approximated value representing π.
    3. If nx is +0𝔽 or nx is -0𝔽, return an implementation-approximated value representing π / 2.
  10. If ny < +0𝔽, then
    1. If nx is +∞𝔽, return -0𝔽.
    2. If nx is -∞𝔽, return an implementation-approximated value representing -π.
    3. If nx is +0𝔽 or nx is -0𝔽, return an implementation-approximated value representing -π / 2.
  11. Assert: nx is finite and is neither +0𝔽 nor -0𝔽.
  12. Return an implementation-approximated value representing the result of the inverse tangent of the quotient (ny) / (nx).

21.3.2.9 Math.cbrt ( x )

Returns the cube root of x.

When the Math.cbrt method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. Return an implementation-approximated value representing the result of the cube root of (n).

21.3.2.10 Math.ceil ( x )

Returns the smallest (closest to -∞) integral Number value that is not less than x. If x is already an integral Number, the result is x.

When the Math.ceil method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n < +0𝔽 and n > -1𝔽, return -0𝔽.
  4. If n is an integral Number, return n.
  5. Return the smallest (closest to -∞) integral Number value that is not less than n.
Note

The value of Math.ceil(x) is the same as the value of -Math.floor(-x).

21.3.2.11 Math.clz32 ( x )

When the Math.clz32 method is called with argument x, the following steps are taken:

  1. Let n be ? ToUint32(x).
  2. Let p be the number of leading zero bits in the unsigned 32-bit binary representation of n.
  3. Return 𝔽(p).
Note

If n is +0𝔽 or n is -0𝔽, this method returns 32𝔽. If the most significant bit of the 32-bit binary encoding of n is 1, this method returns +0𝔽.

21.3.2.12 Math.cos ( x )

Returns the cosine of x. The argument is expressed in radians.

When the Math.cos method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n is +∞𝔽 or n is -∞𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the cosine of (n).

21.3.2.13 Math.cosh ( x )

Returns the hyperbolic cosine of x.

When the Math.cosh method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n is +0𝔽 or n is -0𝔽, return 1𝔽.
  4. Return an implementation-approximated value representing the result of the hyperbolic cosine of (n).
Note

The value of Math.cosh(x) is the same as the value of (Math.exp(x) + Math.exp(-x)) / 2.

21.3.2.14 Math.exp ( x )

Returns the exponential function of x (e raised to the power of x, where e is the base of the natural logarithms).

When the Math.exp method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is +0𝔽 or n is -0𝔽, return 1𝔽.
  4. If n is -∞𝔽, return +0𝔽.
  5. Return an implementation-approximated value representing the result of the exponential function of (n).

21.3.2.15 Math.expm1 ( x )

Returns the result of subtracting 1 from the exponential function of x (e raised to the power of x, where e is the base of the natural logarithms). The result is computed in a way that is accurate even when the value of x is close to 0.

When the Math.expm1 method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, or n is +∞𝔽, return n.
  3. If n is -∞𝔽, return -1𝔽.
  4. Return an implementation-approximated value representing the result of subtracting 1 from the exponential function of (n).

21.3.2.16 Math.floor ( x )

Returns the greatest (closest to +∞) integral Number value that is not greater than x. If x is already an integral Number, the result is x.

When the Math.floor method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n < 1𝔽 and n > +0𝔽, return +0𝔽.
  4. If n is an integral Number, return n.
  5. Return the greatest (closest to +∞) integral Number value that is not greater than n.
Note

The value of Math.floor(x) is the same as the value of -Math.ceil(-x).

21.3.2.17 Math.fround ( x )

When the Math.fround method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, return NaN.
  3. If n is one of +0𝔽, -0𝔽, +∞𝔽, or -∞𝔽, return n.
  4. Let n32 be the result of converting n to a value in IEEE 754-2019 binary32 format using roundTiesToEven mode.
  5. Let n64 be the result of converting n32 to a value in IEEE 754-2019 binary64 format.
  6. Return the ECMAScript Number value corresponding to n64.

21.3.2.18 Math.hypot ( ...args )

Returns the square root of the sum of squares of its arguments.

When the Math.hypot method is called with zero or more arguments which form the rest parameter ...args, the following steps are taken:

  1. Let coerced be a new empty List.
  2. For each element arg of args, do
    1. Let n be ? ToNumber(arg).
    2. Append n to coerced.
  3. Let onlyZero be true.
  4. For each element number of coerced, do
    1. If number is NaN or number is +∞𝔽, return number.
    2. If number is -∞𝔽, return +∞𝔽.
    3. If number is neither +0𝔽 nor -0𝔽, set onlyZero to false.
  5. If onlyZero is true, return +0𝔽.
  6. Return an implementation-approximated value representing the square root of the sum of squares of the mathematical values of the elements of coerced.

The "length" property of the hypot method is 2𝔽.

Note

Implementations should take care to avoid the loss of precision from overflows and underflows that are prone to occur in naive implementations when this function is called with two or more arguments.

21.3.2.19 Math.imul ( x, y )

When Math.imul is called with arguments x and y, the following steps are taken:

  1. Let a be (? ToUint32(x)).
  2. Let b be (? ToUint32(y)).
  3. Let product be (a × b) modulo 232.
  4. If product ≥ 231, return 𝔽(product - 232); otherwise return 𝔽(product).

21.3.2.20 Math.log ( x )

Returns the natural logarithm of x.

When the Math.log method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return -∞𝔽.
  5. If n < +0𝔽, return NaN.
  6. Return an implementation-approximated value representing the result of the natural logarithm of (n).

21.3.2.21 Math.log1p ( x )

Returns the natural logarithm of 1 + x. The result is computed in a way that is accurate even when the value of x is close to zero.

When the Math.log1p method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, or n is +∞𝔽, return n.
  3. If n is -1𝔽, return -∞𝔽.
  4. If n < -1𝔽, return NaN.
  5. Return an implementation-approximated value representing the result of the natural logarithm of 1 + (n).

21.3.2.22 Math.log10 ( x )

Returns the base 10 logarithm of x.

When the Math.log10 method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return -∞𝔽.
  5. If n < +0𝔽, return NaN.
  6. Return an implementation-approximated value representing the result of the base 10 logarithm of (n).

21.3.2.23 Math.log2 ( x )

Returns the base 2 logarithm of x.

When the Math.log2 method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN or n is +∞𝔽, return n.
  3. If n is 1𝔽, return +0𝔽.
  4. If n is +0𝔽 or n is -0𝔽, return -∞𝔽.
  5. If n < +0𝔽, return NaN.
  6. Return an implementation-approximated value representing the result of the base 2 logarithm of (n).

21.3.2.24 Math.max ( ...args )

Given zero or more arguments, calls ToNumber on each of the arguments and returns the largest of the resulting values.

When the Math.max method is called with zero or more arguments which form the rest parameter ...args, the following steps are taken:

  1. Let coerced be a new empty List.
  2. For each element arg of args, do
    1. Let n be ? ToNumber(arg).
    2. Append n to coerced.
  3. Let highest be -∞𝔽.
  4. For each element number of coerced, do
    1. If number is NaN, return NaN.
    2. If number is +0𝔽 and highest is -0𝔽, set highest to +0𝔽.
    3. If number > highest, set highest to number.
  5. Return highest.
Note

The comparison of values to determine the largest value is done using the Abstract Relational Comparison algorithm except that +0𝔽 is considered to be larger than -0𝔽.

The "length" property of the max method is 2𝔽.

21.3.2.25 Math.min ( ...args )

Given zero or more arguments, calls ToNumber on each of the arguments and returns the smallest of the resulting values.

When the Math.min method is called with zero or more arguments which form the rest parameter ...args, the following steps are taken:

  1. Let coerced be a new empty List.
  2. For each element arg of args, do
    1. Let n be ? ToNumber(arg).
    2. Append n to coerced.
  3. Let lowest be +∞𝔽.
  4. For each element number of coerced, do
    1. If number is NaN, return NaN.
    2. If number is -0𝔽 and lowest is +0𝔽, set lowest to -0𝔽.
    3. If number < lowest, set lowest to number.
  5. Return lowest.
Note

The comparison of values to determine the largest value is done using the Abstract Relational Comparison algorithm except that +0𝔽 is considered to be larger than -0𝔽.

The "length" property of the min method is 2𝔽.

21.3.2.26 Math.pow ( base, exponent )

When the Math.pow method is called with arguments base and exponent, the following steps are taken:

  1. Set base to ? ToNumber(base).
  2. Set exponent to ? ToNumber(exponent).
  3. Return ! Number::exponentiate(base, exponent).

21.3.2.27 Math.random ( )

Returns a Number value with positive sign, greater than or equal to +0𝔽 but strictly less than 1𝔽, chosen randomly or pseudo randomly with approximately uniform distribution over that range, using an implementation-defined algorithm or strategy. This function takes no arguments.

Each Math.random function created for distinct realms must produce a distinct sequence of values from successive calls.

21.3.2.28 Math.round ( x )

Returns the Number value that is closest to x and is integral. If two integral Numbers are equally close to x, then the result is the Number value that is closer to +∞. If x is already integral, the result is x.

When the Math.round method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, +∞𝔽, -∞𝔽, or an integral Number, return n.
  3. If n < 0.5𝔽 and n > +0𝔽, return +0𝔽.
  4. If n < +0𝔽 and n-0.5𝔽, return -0𝔽.
  5. Return the integral Number closest to n, preferring the Number closer to +∞ in the case of a tie.
Note 1

Math.round(3.5) returns 4, but Math.round(-3.5) returns -3.

Note 2

The value of Math.round(x) is not always the same as the value of Math.floor(x + 0.5). When x is -0𝔽 or is less than +0𝔽 but greater than or equal to -0.5𝔽, Math.round(x) returns -0𝔽, but Math.floor(x + 0.5) returns +0𝔽. Math.round(x) may also differ from the value of Math.floor(x + 0.5)because of internal rounding when computing x + 0.5.

21.3.2.29 Math.sign ( x )

Returns the sign of x, indicating whether x is positive, negative, or zero.

When the Math.sign method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n < +0𝔽, return -1𝔽.
  4. Return 1𝔽.

21.3.2.30 Math.sin ( x )

Returns the sine of x. The argument is expressed in radians.

When the Math.sin method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n is +∞𝔽 or n is -∞𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the sine of (n).

21.3.2.31 Math.sinh ( x )

Returns the hyperbolic sine of x.

When the Math.sinh method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. Return an implementation-approximated value representing the result of the hyperbolic sine of (n).
Note

The value of Math.sinh(x) is the same as the value of (Math.exp(x) - Math.exp(-x)) / 2.

21.3.2.32 Math.sqrt ( x )

Returns the square root of x.

When the Math.sqrt method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, or n is +∞𝔽, return n.
  3. If n < +0𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the square root of (n).

21.3.2.33 Math.tan ( x )

Returns the tangent of x. The argument is expressed in radians.

When the Math.tan method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n is +∞𝔽, or n is -∞𝔽, return NaN.
  4. Return an implementation-approximated value representing the result of the tangent of (n).

21.3.2.34 Math.tanh ( x )

Returns the hyperbolic tangent of x.

When the Math.tanh method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, or n is -0𝔽, return n.
  3. If n is +∞𝔽, return 1𝔽.
  4. If n is -∞𝔽, return -1𝔽.
  5. Return an implementation-approximated value representing the result of the hyperbolic tangent of (n).
Note

The value of Math.tanh(x) is the same as the value of (Math.exp(x) - Math.exp(-x)) / (Math.exp(x) + Math.exp(-x)).

21.3.2.35 Math.trunc ( x )

Returns the integral part of the number x, removing any fractional digits. If x is already integral, the result is x.

When the Math.trunc method is called with argument x, the following steps are taken:

  1. Let n be ? ToNumber(x).
  2. If n is NaN, n is +0𝔽, n is -0𝔽, n is +∞𝔽, or n is -∞𝔽, return n.
  3. If n < 1𝔽 and n > +0𝔽, return +0𝔽.
  4. If n < +0𝔽 and n > -1𝔽, return -0𝔽.
  5. Return the integral Number nearest n in the direction of +0𝔽.