# module Math

Module Math provides methods for basic trigonometric, logarithmic, and transcendental functions, and for extracting roots.

You can write its constants and method calls thus:

```Math::PI      # => 3.141592653589793
Math::E       # => 2.718281828459045
Math.sin(0.0) # => 0.0
Math.cos(0.0) # => 1.0
```

If you include module Math, you can write simpler forms:

```include Math
PI       # => 3.141592653589793
E        # => 2.718281828459045
sin(0.0) # => 0.0
cos(0.0) # => 1.0
```

For simplicity, the examples here assume:

```include Math
INFINITY = Float::INFINITY
```

The domains and ranges for the methods are denoted by open or closed intervals, using, respectively, parentheses or square brackets:

• An open interval does not include the endpoints:

`(-INFINITY, INFINITY)`
• A closed interval includes the endpoints:

```[-1.0, 1.0]
```
• A half-open interval includes one endpoint, but not the other:

`[1.0, INFINITY)`

Many values returned by Math methods are numerical approximations. This is because many such values are, in mathematics, of infinite precision, while in numerical computation the precision is finite.

Thus, in mathematics, cos(π/2) is exactly zero, but in our computation `cos(PI/2)` is a number very close to zero:

```cos(PI/2) # => 6.123031769111886e-17
```

For very large and very small returned values, we have added formatted numbers for clarity:

```tan(PI/2)  # => 1.633123935319537e+16   # 16331239353195370.0
tan(PI)    # => -1.2246467991473532e-16 # -0.0000000000000001
```

See class `Float` for the constants that affect Ruby’s floating-point arithmetic.

### What’s Here¶ ↑

#### Hypotenuse Function¶ ↑

• `::hypot`: Returns `sqrt(a**2 + b**2)` for the given `a` and `b`.

### Constants

E

Definition of the mathematical constant `E` for Euler’s number (e) as a `Float` number.

PI

Definition of the mathematical constant `PI` as a `Float` number.

### Public Class Methods

acos(x) → float click to toggle source

Returns the arc cosine of `x`.

• Domain: `[-1, 1]`.

• Range: `[0, PI]`.

Examples:

```acos(-1.0) # => 3.141592653589793  # PI
acos(0.0)  # => 1.5707963267948966 # PI/2
acos(1.0)  # => 0.0
```
```static VALUE
math_acos(VALUE unused_obj, VALUE x)
{
math_arc(x, acos)
}```
acosh(x) → float click to toggle source

Returns the inverse hyperbolic cosine of `x`.

• Domain: `[1, INFINITY]`.

• Range: `[0, INFINITY]`.

Examples:

```acosh(1.0)      # => 0.0
acosh(INFINITY) # => Infinity
```
```static VALUE
math_acosh(VALUE unused_obj, VALUE x)
{
double d;

d = Get_Double(x);
domain_check_min(d, 1.0, "acosh");
return DBL2NUM(acosh(d));
}```
asin(x) → float click to toggle source

Returns the arc sine of `x`.

• Domain: `[-1, -1]`.

• Range: `[-PI/2, PI/2]`.

Examples:

```asin(-1.0) # => -1.5707963267948966 # -PI/2
asin(0.0)  # => 0.0
asin(1.0)  # => 1.5707963267948966  # PI/2
```
```static VALUE
math_asin(VALUE unused_obj, VALUE x)
{
math_arc(x, asin)
}```
asinh(x) → float click to toggle source

Returns the inverse hyperbolic sine of `x`.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```asinh(-INFINITY) # => -Infinity
asinh(0.0)       # => 0.0
asinh(INFINITY)  # => Infinity
```
```static VALUE
math_asinh(VALUE unused_obj, VALUE x)
{
return DBL2NUM(asinh(Get_Double(x)));
}```
atan(x) → Float click to toggle source

Returns the arc tangent of `x`.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[-PI/2, PI/2] `.

Examples:

```atan(-INFINITY) # => -1.5707963267948966 # -PI2
atan(-PI)       # => -1.2626272556789115
atan(-PI/2)     # => -1.0038848218538872
atan(0.0)       # => 0.0
atan(PI/2)      # => 1.0038848218538872
atan(PI)        # => 1.2626272556789115
atan(INFINITY)  # => 1.5707963267948966  # PI/2
```
```static VALUE
math_atan(VALUE unused_obj, VALUE x)
{
return DBL2NUM(atan(Get_Double(x)));
}```
atan2(y, x) → float click to toggle source

Returns the arc tangent of `y` and `x` in radians.

• Domain of `y`: `[-INFINITY, INFINITY]`.

• Domain of `x`: `[-INFINITY, INFINITY]`.

• Range: `[-PI, PI]`.

Examples:

```atan2(-1.0, -1.0) # => -2.356194490192345  # -3*PI/4
atan2(-1.0, 0.0)  # => -1.5707963267948966 # -PI/2
atan2(-1.0, 1.0)  # => -0.7853981633974483 # -PI/4
atan2(0.0, -1.0)  # => 3.141592653589793   # PI
```
```static VALUE
math_atan2(VALUE unused_obj, VALUE y, VALUE x)
{
double dx, dy;
dx = Get_Double(x);
dy = Get_Double(y);
if (dx == 0.0 && dy == 0.0) {
if (!signbit(dx))
return DBL2NUM(dy);
if (!signbit(dy))
return DBL2NUM(M_PI);
return DBL2NUM(-M_PI);
}
#ifndef ATAN2_INF_C99
if (isinf(dx) && isinf(dy)) {
/* optimization for FLONUM */
if (dx < 0.0) {
const double dz = (3.0 * M_PI / 4.0);
return (dy < 0.0) ? DBL2NUM(-dz) : DBL2NUM(dz);
}
else {
const double dz = (M_PI / 4.0);
return (dy < 0.0) ? DBL2NUM(-dz) : DBL2NUM(dz);
}
}
#endif
return DBL2NUM(atan2(dy, dx));
}```
atanh(x) → float click to toggle source

Returns the inverse hyperbolic tangent of `x`.

• Domain: `[-1, 1]`.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```atanh(-1.0) # => -Infinity
atanh(0.0)  # => 0.0
atanh(1.0)  # => Infinity
```
```static VALUE
math_atanh(VALUE unused_obj, VALUE x)
{
double d;

d = Get_Double(x);
domain_check_range(d, -1.0, +1.0, "atanh");
/* check for pole error */
if (d == -1.0) return DBL2NUM(-HUGE_VAL);
if (d == +1.0) return DBL2NUM(+HUGE_VAL);
return DBL2NUM(atanh(d));
}```
cbrt(x) → float click to toggle source

Returns the cube root of `x`.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```cbrt(-INFINITY) # => -Infinity
cbrt(-27.0)     # => -3.0
cbrt(-8.0)      # => -2.0
cbrt(-2.0)      # => -1.2599210498948732
cbrt(1.0)       # => 1.0
cbrt(0.0)       # => 0.0
cbrt(1.0)       # => 1.0
cbrt(2.0)       # => 1.2599210498948732
cbrt(8.0)       # => 2.0
cbrt(27.0)      # => 3.0
cbrt(INFINITY)  # => Infinity
```
```static VALUE
math_cbrt(VALUE unused_obj, VALUE x)
{
double f = Get_Double(x);
double r = cbrt(f);
#if defined __GLIBC__
if (isfinite(r) && !(f == 0.0 && r == 0.0)) {
r = (2.0 * r + (f / r / r)) / 3.0;
}
#endif
return DBL2NUM(r);
}```
cos(x) → float click to toggle source

Returns the cosine of `x` in radians.

• Domain: `(-INFINITY, INFINITY)`.

• Range: `[-1.0, 1.0]`.

Examples:

```cos(-PI)   # => -1.0
cos(-PI/2) # => 6.123031769111886e-17 # 0.0000000000000001
cos(0.0)   # => 1.0
cos(PI/2)  # => 6.123031769111886e-17 # 0.0000000000000001
cos(PI)    # => -1.0
```
```static VALUE
math_cos(VALUE unused_obj, VALUE x)
{
return DBL2NUM(cos(Get_Double(x)));
}```
cosh(x) → float click to toggle source

Returns the hyperbolic cosine of `x` in radians.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[1, INFINITY]`.

Examples:

```cosh(-INFINITY) # => Infinity
cosh(0.0)       # => 1.0
cosh(INFINITY)  # => Infinity
```
```static VALUE
math_cosh(VALUE unused_obj, VALUE x)
{
return DBL2NUM(cosh(Get_Double(x)));
}```
erf(x) → float click to toggle source

Returns the value of the Gauss error function for `x`.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[-1, 1]`.

Examples:

```erf(-INFINITY) # => -1.0
erf(0.0)       # => 0.0
erf(INFINITY)  # => 1.0
```

Related: `Math.erfc`.

```static VALUE
math_erf(VALUE unused_obj, VALUE x)
{
return DBL2NUM(erf(Get_Double(x)));
}```
erfc(x) → Float click to toggle source

Returns the value of the complementary error function for `x`.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[0, 2]`.

Examples:

```erfc(-INFINITY) # => 2.0
erfc(0.0)       # => 1.0
erfc(INFINITY)  # => 0.0
```

Related: `Math.erf`.

```static VALUE
math_erfc(VALUE unused_obj, VALUE x)
{
return DBL2NUM(erfc(Get_Double(x)));
}```
exp(x) → float click to toggle source

Returns `e` raised to the `x` power.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[0, INFINITY]`.

Examples:

```exp(-INFINITY) # => 0.0
exp(-1.0)      # => 0.36787944117144233 # 1.0/E
exp(0.0)       # => 1.0
exp(0.5)       # => 1.6487212707001282  # sqrt(E)
exp(1.0)       # => 2.718281828459045   # E
exp(2.0)       # => 7.38905609893065    # E**2
exp(INFINITY)  # => Infinity
```
```static VALUE
math_exp(VALUE unused_obj, VALUE x)
{
return DBL2NUM(exp(Get_Double(x)));
}```
frexp(x) → [fraction, exponent] click to toggle source

Returns a 2-element array containing the normalized signed float `fraction` and integer `exponent` of `x` such that:

```x = fraction * 2**exponent
```
• Domain: `[-INFINITY, INFINITY]`.

• `Range` `[-INFINITY, INFINITY]`.

Examples:

```frexp(-INFINITY) # => [-Infinity, -1]
frexp(-2.0)      # => [-0.5, 2]
frexp(-1.0)      # => [-0.5, 1]
frexp(0.0)       # => [0.0, 0]
frexp(1.0)       # => [0.5, 1]
frexp(2.0)       # => [0.5, 2]
frexp(INFINITY)  # => [Infinity, -1]
```

Related: `Math.ldexp` (inverse of `Math.frexp`).

```static VALUE
math_frexp(VALUE unused_obj, VALUE x)
{
double d;
int exp;

d = frexp(Get_Double(x), &exp);
return rb_assoc_new(DBL2NUM(d), INT2NUM(exp));
}```
gamma(x) → float click to toggle source

Returns the value of the gamma function for `x`.

• Domain: `(-INFINITY, INFINITY]` excluding negative integers.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```gamma(-2.5)      # => -0.9453087204829431
gamma(-1.5)      # => 2.3632718012073513
gamma(-0.5)      # => -3.5449077018110375
gamma(0.0)      # => Infinity
gamma(1.0)      # => 1.0
gamma(2.0)      # => 1.0
gamma(3.0)      # => 2.0
gamma(4.0)      # => 6.0
gamma(5.0)      # => 24.0
```

Related: `Math.lgamma`.

```static VALUE
math_gamma(VALUE unused_obj, VALUE x)
{
static const double fact_table[] = {
/* fact(0) */ 1.0,
/* fact(1) */ 1.0,
/* fact(2) */ 2.0,
/* fact(3) */ 6.0,
/* fact(4) */ 24.0,
/* fact(5) */ 120.0,
/* fact(6) */ 720.0,
/* fact(7) */ 5040.0,
/* fact(8) */ 40320.0,
/* fact(9) */ 362880.0,
/* fact(10) */ 3628800.0,
/* fact(11) */ 39916800.0,
/* fact(12) */ 479001600.0,
/* fact(13) */ 6227020800.0,
/* fact(14) */ 87178291200.0,
/* fact(15) */ 1307674368000.0,
/* fact(16) */ 20922789888000.0,
/* fact(17) */ 355687428096000.0,
/* fact(18) */ 6402373705728000.0,
/* fact(19) */ 121645100408832000.0,
/* fact(20) */ 2432902008176640000.0,
/* fact(21) */ 51090942171709440000.0,
/* fact(22) */ 1124000727777607680000.0,
/* fact(23)=25852016738884976640000 needs 56bit mantissa which is
* impossible to represent exactly in IEEE 754 double which have
* 53bit mantissa. */
};
enum {NFACT_TABLE = numberof(fact_table)};
double d;
d = Get_Double(x);
/* check for domain error */
if (isinf(d)) {
if (signbit(d)) domain_error("gamma");
return DBL2NUM(HUGE_VAL);
}
if (d == 0.0) {
return signbit(d) ? DBL2NUM(-HUGE_VAL) : DBL2NUM(HUGE_VAL);
}
if (d == floor(d)) {
domain_check_min(d, 0.0, "gamma");
if (1.0 <= d && d <= (double)NFACT_TABLE) {
return DBL2NUM(fact_table[(int)d - 1]);
}
}
return DBL2NUM(tgamma(d));
}```
hypot(a, b) → float click to toggle source

Returns `sqrt(a**2 + b**2)`, which is the length of the longest side `c` (the hypotenuse) of the right triangle whose other sides have lengths `a` and `b`.

• Domain of `a`: `[-INFINITY, INFINITY]`.

• Domain of +ab: `[-INFINITY, INFINITY]`.

• Range: `[0, INFINITY]`.

Examples:

```hypot(0.0, 1.0)       # => 1.0
hypot(1.0, 1.0)       # => 1.4142135623730951 # sqrt(2.0)
hypot(3.0, 4.0)       # => 5.0
hypot(5.0, 12.0)      # => 13.0
hypot(1.0, sqrt(3.0)) # => 1.9999999999999998 # Near 2.0
```

Note that if either argument is `INFINITY` or `-INFINITY`, the result is `Infinity`.

```static VALUE
math_hypot(VALUE unused_obj, VALUE x, VALUE y)
{
return DBL2NUM(hypot(Get_Double(x), Get_Double(y)));
}```
ldexp(fraction, exponent) → float click to toggle source

Returns the value of `fraction * 2**exponent`.

• Domain of `fraction`: `[0.0, 1.0)`.

• Domain of `exponent`: `[0, 1024]` (larger values are equivalent to 1024).

Examples:

```ldexp(-INFINITY, -1) # => -Infinity
ldexp(-0.5, 2)       # => -2.0
ldexp(-0.5, 1)       # => -1.0
ldexp(0.0, 0)        # => 0.0
ldexp(-0.5, 1)       # => 1.0
ldexp(-0.5, 2)       # => 2.0
ldexp(INFINITY, -1)  # => Infinity
```

Related: `Math.frexp` (inverse of `Math.ldexp`).

```static VALUE
math_ldexp(VALUE unused_obj, VALUE x, VALUE n)
{
return DBL2NUM(ldexp(Get_Double(x), NUM2INT(n)));
}```
lgamma(x) → [float, -1 or 1] click to toggle source

Returns a 2-element array equivalent to:

```[Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
```
• Domain: `(-INFINITY, INFINITY]`.

• `Range` of first element: `(-INFINITY, INFINITY]`.

• Second element is -1 or 1.

Examples:

```lgamma(-4.0) # => [Infinity, -1]
lgamma(-3.0) # => [Infinity, -1]
lgamma(-2.0) # => [Infinity, -1]
lgamma(-1.0) # => [Infinity, -1]
lgamma(0.0)  # => [Infinity, 1]

lgamma(1.0)  # => [0.0, 1]
lgamma(2.0)  # => [0.0, 1]
lgamma(3.0)  # => [0.6931471805599436, 1]
lgamma(4.0)  # => [1.7917594692280545, 1]

lgamma(-2.5) # => [-0.05624371649767279, -1]
lgamma(-1.5) # => [0.8600470153764797, 1]
lgamma(-0.5) # => [1.265512123484647, -1]
lgamma(0.5)  # => [0.5723649429247004, 1]
lgamma(1.5)  # => [-0.12078223763524676, 1]
lgamma(2.5)      # => [0.2846828704729205, 1]
```

Related: `Math.gamma`.

```static VALUE
math_lgamma(VALUE unused_obj, VALUE x)
{
double d;
int sign=1;
VALUE v;
d = Get_Double(x);
/* check for domain error */
if (isinf(d)) {
if (signbit(d)) domain_error("lgamma");
return rb_assoc_new(DBL2NUM(HUGE_VAL), INT2FIX(1));
}
if (d == 0.0) {
VALUE vsign = signbit(d) ? INT2FIX(-1) : INT2FIX(+1);
return rb_assoc_new(DBL2NUM(HUGE_VAL), vsign);
}
v = DBL2NUM(lgamma_r(d, &sign));
return rb_assoc_new(v, INT2FIX(sign));
}```
log(x, base = Math::E) → Float click to toggle source

Returns the base `base` logarithm of `x`.

• Domain: `[0, INFINITY]`.

• Range: `[-INFINITY, INFINITY)]`.

Examples:

```log(0.0)        # => -Infinity
log(1.0)        # => 0.0
log(E)          # => 1.0
log(INFINITY)   # => Infinity

log(0.0, 2.0)   # => -Infinity
log(1.0, 2.0)   # => 0.0
log(2.0, 2.0)   # => 1.0

log(0.0, 10.0)  # => -Infinity
log(1.0, 10.0)  # => 0.0
log(10.0, 10.0) # => 1.0
```
```static VALUE
math_log(int argc, const VALUE *argv, VALUE unused_obj)
{
return rb_math_log(argc, argv);
}```
log10(x) → float click to toggle source

Returns the base 10 logarithm of `x`.

• Domain: `[0, INFINITY]`.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```log10(0.0)      # => -Infinity
log10(1.0)      # => 0.0
log10(10.0)     # => 1.0
log10(INFINITY) # => Infinity
```
```static VALUE
math_log10(VALUE unused_obj, VALUE x)
{
size_t numbits;
double d = get_double_rshift(x, &numbits);

domain_check_min(d, 0.0, "log10");
/* check for pole error */
if (d == 0.0) return DBL2NUM(-HUGE_VAL);

return DBL2NUM(log10(d) + numbits * log10(2)); /* log10(d * 2 ** numbits) */
}```
log2(x) → float click to toggle source

Returns the base 2 logarithm of `x`.

• Domain: `[0, INFINITY]`.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```log2(0.0)      # => -Infinity
log2(1.0)      # => 0.0
log2(2.0)      # => 1.0
log2(INFINITY) # => Infinity
```
```static VALUE
math_log2(VALUE unused_obj, VALUE x)
{
size_t numbits;
double d = get_double_rshift(x, &numbits);

domain_check_min(d, 0.0, "log2");
/* check for pole error */
if (d == 0.0) return DBL2NUM(-HUGE_VAL);

return DBL2NUM(log2(d) + numbits); /* log2(d * 2 ** numbits) */
}```
sin(x) → float click to toggle source

Returns the sine of `x` in radians.

• Domain: `(-INFINITY, INFINITY)`.

• Range: `[-1.0, 1.0]`.

Examples:

```sin(-PI)   # => -1.2246063538223773e-16 # -0.0000000000000001
sin(-PI/2) # => -1.0
sin(0.0)   # => 0.0
sin(PI/2)  # => 1.0
sin(PI)    # => 1.2246063538223773e-16  # 0.0000000000000001
```
```static VALUE
math_sin(VALUE unused_obj, VALUE x)
{
return DBL2NUM(sin(Get_Double(x)));
}```
sinh(x) → float click to toggle source

Returns the hyperbolic sine of `x` in radians.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[-INFINITY, INFINITY]`.

Examples:

```sinh(-INFINITY) # => -Infinity
sinh(0.0)       # => 0.0
sinh(INFINITY)  # => Infinity
```
```static VALUE
math_sinh(VALUE unused_obj, VALUE x)
{
return DBL2NUM(sinh(Get_Double(x)));
}```
sqrt(x) → float click to toggle source

Returns the principal (non-negative) square root of `x`.

• Domain: `[0, INFINITY]`.

• Range: `[0, INFINITY]`.

Examples:

```sqrt(0.0)      # => 0.0
sqrt(0.5)      # => 0.7071067811865476
sqrt(1.0)      # => 1.0
sqrt(2.0)      # => 1.4142135623730951
sqrt(4.0)      # => 2.0
sqrt(9.0)      # => 3.0
sqrt(INFINITY) # => Infinity
```
```static VALUE
math_sqrt(VALUE unused_obj, VALUE x)
{
return rb_math_sqrt(x);
}```
tan(x) → float click to toggle source

Returns the tangent of `x` in radians.

• Domain: `(-INFINITY, INFINITY)`.

• Range: `(-INFINITY, INFINITY)`.

Examples:

```tan(-PI)   # => 1.2246467991473532e-16  # -0.0000000000000001
tan(-PI/2) # => -1.633123935319537e+16  # -16331239353195370.0
tan(0.0)   # => 0.0
tan(PI/2)  # => 1.633123935319537e+16   # 16331239353195370.0
tan(PI)    # => -1.2246467991473532e-16 # -0.0000000000000001
```
```static VALUE
math_tan(VALUE unused_obj, VALUE x)
{
return DBL2NUM(tan(Get_Double(x)));
}```
tanh(x) → float click to toggle source

Returns the hyperbolic tangent of `x` in radians.

• Domain: `[-INFINITY, INFINITY]`.

• Range: `[-1, 1]`.

Examples:

```tanh(-INFINITY) # => -1.0
tanh(0.0)       # => 0.0
tanh(INFINITY)  # => 1.0
```
```static VALUE
math_tanh(VALUE unused_obj, VALUE x)
{
return DBL2NUM(tanh(Get_Double(x)));
}```