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.141592653589793Math::E# => 2.718281828459045Math.sin(0.0)# => 0.0Math.cos(0.0)# => 1.0
If you include module Math, you can write simpler forms:
includeMathPI# => 3.141592653589793E# => 2.718281828459045sin(0.0)# => 0.0cos(0.0)# => 1.0
For simplicity, the examples here assume:
includeMathINFINITY =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 computationcos(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.0tan(PI)# => -1.2246467991473532e-16 # -0.0000000000000001
See classFloat for the constants that affect Ruby’s floating-point arithmetic.
What’s Here¶↑
Trigonometric Functions¶↑
::cos: Returns the cosine of the given argument.::sin: Returns the sine of the given argument.::tan: Returns the tangent of the given argument.
Inverse Trigonometric Functions¶↑
::acos: Returns the arc cosine of the given argument.::asin: Returns the arc sine of the given argument.::atan: Returns the arc tangent of the given argument.::atan2: Returns the arg tangent of two given arguments.
Hyperbolic Trigonometric Functions¶↑
::cosh: Returns the hyperbolic cosine of the given argument.::sinh: Returns the hyperbolic sine of the given argument.::tanh: Returns the hyperbolic tangent of the given argument.
Inverse Hyperbolic Trigonometric Functions¶↑
::acosh: Returns the inverse hyperbolic cosine of the given argument.::asinh: Returns the inverse hyperbolic sine of the given argument.::atanh: Returns the inverse hyperbolic tangent of the given argument.
Exponentiation and Logarithmic Functions¶↑
::exp: Returns the value of a given value raised to a given power.::log: Returns the logarithm of a given value in a given base.::log10: Returns the base 10 logarithm of the given argument.::log2: Returns the base 2 logarithm of the given argument.
Fraction and Exponent Functions¶↑
::frexp: Returns the fraction and exponent of the given argument.::ldexp: Returns the value for a given fraction and exponent.
Root Functions¶↑
::cbrt: Returns the cube root of the given argument.::sqrt: Returns the square root of the given argument.
Error Functions¶↑
::erf: Returns the value of the Gauss error function for the given argument.::erfc: Returns the value of the complementary error function for the given argument.
Gamma Functions¶↑
::gamma: Returns the value of the gamma function for the given argument.::lgamma: Returns the value of the logarithmic gamma function for the given argument.
Hypotenuse Function¶↑
::hypot: Returnssqrt(a**2 + b**2)for the givenaandb.
Constants
Public Class Methods
Source
static VALUEmath_acos(VALUE unused_obj, VALUE x){ math_arc(x, acos)}Returns thearc cosine ofx.
Domain:
[-1, 1].Range:
[0, PI].
Examples:
acos(-1.0)# => 3.141592653589793 # PIacos(0.0)# => 1.5707963267948966 # PI/2acos(1.0)# => 0.0
Source
static VALUEmath_acosh(VALUE unused_obj, VALUE x){ double d; d = Get_Double(x); domain_check_min(d, 1.0, "acosh"); return DBL2NUM(acosh(d));}Returns theinverse hyperbolic cosine ofx.
Domain:
[1, INFINITY].Range:
[0, INFINITY].
Examples:
acosh(1.0)# => 0.0acosh(INFINITY)# => Infinity
Source
static VALUEmath_asin(VALUE unused_obj, VALUE x){ math_arc(x, asin)}Returns thearc sine ofx.
Domain:
[-1, -1].Range:
[-PI/2, PI/2].
Examples:
asin(-1.0)# => -1.5707963267948966 # -PI/2asin(0.0)# => 0.0asin(1.0)# => 1.5707963267948966 # PI/2
Source
static VALUEmath_asinh(VALUE unused_obj, VALUE x){ return DBL2NUM(asinh(Get_Double(x)));}Returns theinverse hyperbolic sine ofx.
Domain:
[-INFINITY, INFINITY].Range:
[-INFINITY, INFINITY].
Examples:
asinh(-INFINITY)# => -Infinityasinh(0.0)# => 0.0asinh(INFINITY)# => Infinity
Source
static VALUEmath_atan(VALUE unused_obj, VALUE x){ return DBL2NUM(atan(Get_Double(x)));}Returns thearc tangent ofx.
Domain:
[-INFINITY, INFINITY].Range:
[-PI/2, PI/2].
Examples:
atan(-INFINITY)# => -1.5707963267948966 # -PI2atan(-PI)# => -1.2626272556789115atan(-PI/2)# => -1.0038848218538872atan(0.0)# => 0.0atan(PI/2)# => 1.0038848218538872atan(PI)# => 1.2626272556789115atan(INFINITY)# => 1.5707963267948966 # PI/2
Source
static VALUEmath_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));}Returns thearc tangent ofy andx inradians.
Domain of
y:[-INFINITY, INFINITY].Domain of
x:[-INFINITY, INFINITY].Range:
[-PI, PI].
Examples:
atan2(-1.0,-1.0)# => -2.356194490192345 # -3*PI/4atan2(-1.0,0.0)# => -1.5707963267948966 # -PI/2atan2(-1.0,1.0)# => -0.7853981633974483 # -PI/4atan2(0.0,-1.0)# => 3.141592653589793 # PI
Source
static VALUEmath_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));}Returns theinverse hyperbolic tangent ofx.
Domain:
[-1, 1].Range:
[-INFINITY, INFINITY].
Examples:
atanh(-1.0)# => -Infinityatanh(0.0)# => 0.0atanh(1.0)# => Infinity
Source
static VALUEmath_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);}Returns thecube root ofx.
Domain:
[-INFINITY, INFINITY].Range:
[-INFINITY, INFINITY].
Examples:
cbrt(-INFINITY)# => -Infinitycbrt(-27.0)# => -3.0cbrt(-8.0)# => -2.0cbrt(-2.0)# => -1.2599210498948732cbrt(1.0)# => 1.0cbrt(0.0)# => 0.0cbrt(1.0)# => 1.0cbrt(2.0)# => 1.2599210498948732cbrt(8.0)# => 2.0cbrt(27.0)# => 3.0cbrt(INFINITY)# => Infinity
Source
static VALUEmath_cos(VALUE unused_obj, VALUE x){ return DBL2NUM(cos(Get_Double(x)));}Returns thecosine ofx inradians.
Domain:
(-INFINITY, INFINITY).Range:
[-1.0, 1.0].
Examples:
cos(-PI)# => -1.0cos(-PI/2)# => 6.123031769111886e-17 # 0.0000000000000001cos(0.0)# => 1.0cos(PI/2)# => 6.123031769111886e-17 # 0.0000000000000001cos(PI)# => -1.0
Source
static VALUEmath_cosh(VALUE unused_obj, VALUE x){ return DBL2NUM(cosh(Get_Double(x)));}Returns thehyperbolic cosine ofx inradians.
Domain:
[-INFINITY, INFINITY].Range:
[1, INFINITY].
Examples:
cosh(-INFINITY)# => Infinitycosh(0.0)# => 1.0cosh(INFINITY)# => Infinity
Source
static VALUEmath_erf(VALUE unused_obj, VALUE x){ return DBL2NUM(erf(Get_Double(x)));}Returns the value of theGauss error function forx.
Domain:
[-INFINITY, INFINITY].Range:
[-1, 1].
Examples:
erf(-INFINITY)# => -1.0erf(0.0)# => 0.0erf(INFINITY)# => 1.0
Related:Math.erfc.
Source
static VALUEmath_erfc(VALUE unused_obj, VALUE x){ return DBL2NUM(erfc(Get_Double(x)));}Returns the value of thecomplementary error function forx.
Domain:
[-INFINITY, INFINITY].Range:
[0, 2].
Examples:
erfc(-INFINITY)# => 2.0erfc(0.0)# => 1.0erfc(INFINITY)# => 0.0
Related:Math.erf.
Source
static VALUEmath_exp(VALUE unused_obj, VALUE x){ return DBL2NUM(exp(Get_Double(x)));}Returnse raised to thex power.
Domain:
[-INFINITY, INFINITY].Range:
[0, INFINITY].
Examples:
exp(-INFINITY)# => 0.0exp(-1.0)# => 0.36787944117144233 # 1.0/Eexp(0.0)# => 1.0exp(0.5)# => 1.6487212707001282 # sqrt(E)exp(1.0)# => 2.718281828459045 # Eexp(2.0)# => 7.38905609893065 # E**2exp(INFINITY)# => Infinity
Source
static VALUEmath_expm1(VALUE unused_obj, VALUE x){ return DBL2NUM(expm1(Get_Double(x)));}Returns “exp(x) - 1”,e raised to thex power, minus 1.
Domain:
[-INFINITY, INFINITY].Range:
[-1.0, INFINITY].
Examples:
expm1(-INFINITY)# => 0.0expm1(-1.0)# => -0.6321205588285577 # 1.0/E - 1expm1(0.0)# => 0.0expm1(0.5)# => 0.6487212707001282 # sqrt(E) - 1expm1(1.0)# => 1.718281828459045 # E - 1expm1(2.0)# => 6.38905609893065 # E**2 - 1expm1(INFINITY)# => Infinity
Source
static VALUEmath_frexp(VALUE unused_obj, VALUE x){ double d; int exp; d = frexp(Get_Double(x), &exp); return rb_assoc_new(DBL2NUM(d), INT2NUM(exp));}Returns a 2-element array containing the normalized signed floatfraction and integerexponent ofx such that:
x =fraction*2**exponent
SeeIEEE 754 double-precision binary floating-point format: binary64.
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 ofMath.frexp).
Source
static VALUEmath_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));}Returns the value of thegamma function forx.
Domain:
(-INFINITY, INFINITY]excluding negative integers.Range:
[-INFINITY, INFINITY].
Examples:
gamma(-2.5)# => -0.9453087204829431gamma(-1.5)# => 2.3632718012073513gamma(-0.5)# => -3.5449077018110375gamma(0.0)# => Infinitygamma(1.0)# => 1.0gamma(2.0)# => 1.0gamma(3.0)# => 2.0gamma(4.0)# => 6.0gamma(5.0)# => 24.0
Related:Math.lgamma.
Source
static VALUEmath_hypot(VALUE unused_obj, VALUE x, VALUE y){ return DBL2NUM(hypot(Get_Double(x), Get_Double(y)));}Returnssqrt(a**2 + b**2), which is the length of the longest sidec (the hypotenuse) of the right triangle whose other sides have lengthsa andb.
Domain of
a:[-INFINITY, INFINITY].Domain of +ab:
[-INFINITY, INFINITY].Range:
[0, INFINITY].
Examples:
hypot(0.0,1.0)# => 1.0hypot(1.0,1.0)# => 1.4142135623730951 # sqrt(2.0)hypot(3.0,4.0)# => 5.0hypot(5.0,12.0)# => 13.0hypot(1.0,sqrt(3.0))# => 1.9999999999999998 # Near 2.0
Note that if either argument isINFINITY or-INFINITY, the result isInfinity.
Source
static VALUEmath_ldexp(VALUE unused_obj, VALUE x, VALUE n){ return DBL2NUM(ldexp(Get_Double(x), NUM2INT(n)));}Returns the value offraction * 2**exponent.
Domain of
fraction:[0.0, 1.0).Domain of
exponent:[0, 1024](larger values are equivalent to 1024).
SeeIEEE 754 double-precision binary floating-point format: binary64.
Examples:
ldexp(-INFINITY,-1)# => -Infinityldexp(-0.5,2)# => -2.0ldexp(-0.5,1)# => -1.0ldexp(0.0,0)# => 0.0ldexp(-0.5,1)# => 1.0ldexp(-0.5,2)# => 2.0ldexp(INFINITY,-1)# => Infinity
Related:Math.frexp (inverse ofMath.ldexp).
Source
static VALUEmath_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));}Returns a 2-element array equivalent to:
[Math.log(Math.gamma(x).abs),Math.gamma(x)<0?-1:1]
Domain:
(-INFINITY, INFINITY].Rangeof 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.
Source
static VALUEmath_log(int argc, const VALUE *argv, VALUE unused_obj){ return rb_math_log(argc, argv);}Returns the basebaselogarithm ofx.
Domain:
[0, INFINITY].Range:
[-INFINITY, INFINITY)].
Examples:
log(0.0)# => -Infinitylog(1.0)# => 0.0log(E)# => 1.0log(INFINITY)# => Infinitylog(0.0,2.0)# => -Infinitylog(1.0,2.0)# => 0.0log(2.0,2.0)# => 1.0log(0.0,10.0)# => -Infinitylog(1.0,10.0)# => 0.0log(10.0,10.0)# => 1.0
Source
static VALUEmath_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) */}Returns the base 10logarithm ofx.
Domain:
[0, INFINITY].Range:
[-INFINITY, INFINITY].
Examples:
log10(0.0)# => -Infinitylog10(1.0)# => 0.0log10(10.0)# => 1.0log10(INFINITY)# => Infinity
Source
static VALUEmath_log1p(VALUE unused_obj, VALUE x){ size_t numbits; double d = get_double_rshift(x, &numbits); if (numbits != 0) { x = rb_big_plus(x, INT2FIX(1)); d = math_log_split(x, &numbits); /* check for pole error */ if (d == 0.0) return DBL2NUM(-HUGE_VAL); d = log(d); d += numbits * M_LN2; return DBL2NUM(d); } domain_check_min(d, -1.0, "log1p"); /* check for pole error */ if (d == -1.0) return DBL2NUM(-HUGE_VAL); return DBL2NUM(log1p(d)); /* log10(d * 2 ** numbits) */}Returns “log(x + 1)”, the baseElogarithm of (x + 1).
Domain:
[-1, INFINITY].Range:
[-INFINITY, INFINITY].
Examples:
log1p(-1.0)# => -Infinitylog1p(0.0)# => 0.0log1p(E-1)# => 1.0log1p(INFINITY)# => Infinity
Source
static VALUEmath_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) */}Returns the base 2logarithm ofx.
Domain:
[0, INFINITY].Range:
[-INFINITY, INFINITY].
Examples:
log2(0.0)# => -Infinitylog2(1.0)# => 0.0log2(2.0)# => 1.0log2(INFINITY)# => Infinity
Source
static VALUEmath_sin(VALUE unused_obj, VALUE x){ return DBL2NUM(sin(Get_Double(x)));}Returns thesine ofx inradians.
Domain:
(-INFINITY, INFINITY).Range:
[-1.0, 1.0].
Examples:
sin(-PI)# => -1.2246063538223773e-16 # -0.0000000000000001sin(-PI/2)# => -1.0sin(0.0)# => 0.0sin(PI/2)# => 1.0sin(PI)# => 1.2246063538223773e-16 # 0.0000000000000001
Source
static VALUEmath_sinh(VALUE unused_obj, VALUE x){ return DBL2NUM(sinh(Get_Double(x)));}Returns thehyperbolic sine ofx inradians.
Domain:
[-INFINITY, INFINITY].Range:
[-INFINITY, INFINITY].
Examples:
sinh(-INFINITY)# => -Infinitysinh(0.0)# => 0.0sinh(INFINITY)# => Infinity
Source
static VALUEmath_sqrt(VALUE unused_obj, VALUE x){ return rb_math_sqrt(x);}Returns the principal (non-negative)square root ofx.
Domain:
[0, INFINITY].Range:
[0, INFINITY].
Examples:
sqrt(0.0)# => 0.0sqrt(0.5)# => 0.7071067811865476sqrt(1.0)# => 1.0sqrt(2.0)# => 1.4142135623730951sqrt(4.0)# => 2.0sqrt(9.0)# => 3.0sqrt(INFINITY)# => Infinity
Source
static VALUEmath_tan(VALUE unused_obj, VALUE x){ return DBL2NUM(tan(Get_Double(x)));}Returns thetangent ofx inradians.
Domain:
(-INFINITY, INFINITY).Range:
(-INFINITY, INFINITY).
Examples:
tan(-PI)# => 1.2246467991473532e-16 # -0.0000000000000001tan(-PI/2)# => -1.633123935319537e+16 # -16331239353195370.0tan(0.0)# => 0.0tan(PI/2)# => 1.633123935319537e+16 # 16331239353195370.0tan(PI)# => -1.2246467991473532e-16 # -0.0000000000000001
Source
static VALUEmath_tanh(VALUE unused_obj, VALUE x){ return DBL2NUM(tanh(Get_Double(x)));}Returns thehyperbolic tangent ofx inradians.
Domain:
[-INFINITY, INFINITY].Range:
[-1, 1].
Examples:
tanh(-INFINITY)# => -1.0tanh(0.0)# => 0.0tanh(INFINITY)# => 1.0