模組 Math

模組 Math 提供基本三角函數、對數函數和超越函數，以及開根號的方法。

您可以這樣撰寫其常數和方法呼叫

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

如果您包含模組 Math，則可以撰寫更簡單的形式

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

為了簡潔起見，此處的範例假設

include Math
INFINITY = Float::INFINITY

方法的定義域和值域使用開區間或閉區間表示，分別使用括號或方括號

開區間不包含端點
```
(-INFINITY, INFINITY)
```
閉區間包含端點
```
[-1.0, 1.0]
```
半開區間包含一個端點，但不包含另一個端點
```
[1.0, INFINITY)
```

Math 方法傳回的許多值都是數值近似值。這是因為在數學中，許多此類值具有無限精度，而在數值計算中，精度是有限的。

因此，在數學中，cos(π/2) 精確等於零，但在我們的計算中，cos(PI/2) 是非常接近零的數字

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

對於非常大或非常小的傳回值，我們已新增格式化的數字以提高清晰度

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

請參閱類別 Float，以了解影響 Ruby 浮點運算的常數。

此處內容¶ ↑

三角函數¶ ↑

::cos：傳回給定參數的餘弦。
::sin：傳回給定參數的正弦。
::tan：傳回給定參數的正切。

反三角函數¶ ↑

::acos：傳回給定參數的反正弦。
::asin：傳回給定參數的反正切。
::atan：傳回給定參數的反正切。
::atan2：傳回兩個給定參數的反正切。

雙曲函數¶ ↑

::cosh：傳回給定參數的雙曲餘弦。
::sinh：傳回給定參數的雙曲正弦。
::tanh：傳回給定參數的雙曲正切。

雙曲函數的反函數¶ ↑

::acosh：傳回給定參數的雙曲餘弦反函數。
::asinh：傳回給定參數的雙曲正弦反函數。
::atanh：傳回給定參數的雙曲正切反函數。

指數函數和對數函數¶ ↑

::exp：傳回給定值乘以給定次方的值。
::log：傳回給定值在給定底數下的對數。
::log10：傳回給定參數的以 10 為底數的對數。
::log2：傳回給定參數的以 2 為底數的對數。

分數和指數函數¶ ↑

::frexp：傳回給定參數的分數和指數。
::ldexp：傳回給定分數和指數的值。

根號函數¶ ↑

::cbrt：傳回給定參數的立方根。
::sqrt：傳回給定參數的平方根。

誤差函數¶ ↑

::erf：傳回給定參數的高斯誤差函數值。
::erfc：傳回給定參數的互補誤差函數值。

伽瑪函數¶ ↑

::gamma：傳回給定參數的伽瑪函數值。
::lgamma：傳回給定參數的對數伽瑪函數值。

斜邊函數¶ ↑

::hypot：傳回給定 a 和 b 的 sqrt(a**2 + b**2)。

常數

E: 數學常數 E 的定義，為歐拉數 (e)，表示為 Float 數字。
PI: 數學常數 PI 的定義，表示為 Float 數字。

公開類別方法

acos(x) → float 按一下以切換來源

傳回 x 的反餘弦。

網域：[-1, 1]。
範圍：[0, PI]。

範例

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 按一下以切換來源

傳回 x 的反雙曲餘弦。

網域：[1, 無窮大]。
範圍：[0, 無窮大]。

範例

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 按一下以切換來源

傳回 x 的反正弦。

網域：[-1, -1]。
範圍：[-PI/2, PI/2]。

範例

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 按一下以切換來源

傳回 x 的反雙曲正弦。

網域：[-無窮大, 無窮大]。
範圍：[-無窮大, 無窮大]。

範例

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 按一下以切換來源

傳回 x 的反正切。

網域：[-無窮大, 無窮大]。
範圍：[-PI/2, PI/2] 。

範例

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 按一下以切換來源

傳回 y 和 x 的反正切，單位為弧度。

y 的網域：[-無窮大, 無窮大]。
x 的網域：[-無窮大, 無窮大]。
範圍：[-PI, PI]。

範例

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 按一下以切換來源

傳回 x 的反雙曲正切。

網域：[-1, 1]。
範圍：[-無窮大, 無窮大]。

範例

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 按一下切換來源

傳回 x 的立方根。

網域：[-無窮大, 無窮大]。
範圍：[-無窮大, 無窮大]。

範例

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 按一下切換來源

傳回 x 的餘弦，單位為弧度。

定義域：(-INFINITY, INFINITY)。
值域：[-1.0, 1.0]。

範例

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 按一下切換來源

傳回 x 的雙曲餘弦，單位為弧度。

網域：[-無窮大, 無窮大]。
值域：[1, INFINITY]。

範例

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 按一下切換來源

傳回 x 的高斯誤差函數值。

網域：[-無窮大, 無窮大]。
值域：[-1, 1]。

範例

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

相關函數：Math.erfc。

static VALUE
math_erf(VALUE unused_obj, VALUE x)
{
    return DBL2NUM(erf(Get_Double(x)));
}

erfc(x) → Float 按一下切換來源

傳回 x 的互補誤差函數值。

網域：[-無窮大, 無窮大]。
值域：[0, 2]。

範例

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

相關函數：Math.erf。

static VALUE
math_erfc(VALUE unused_obj, VALUE x)
{
    return DBL2NUM(erfc(Get_Double(x)));
}

exp(x) → float 按一下切換來源

傳回 e 的 x 次方。

網域：[-無窮大, 無窮大]。
範圍：[0, 無窮大]。

範例

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] 按一下切換來源

傳回一個包含 x 的正規化有號浮點數 fraction 和整數 exponent 的 2 元素陣列，使得

x = fraction * 2**exponent

請參閱 IEEE 754 雙精度二進制浮點數格式：binary64。

網域：[-無窮大, 無窮大]。
Range [-INFINITY, INFINITY]。

範例

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]

相關函數：Math.ldexp（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 按一下切換來源

傳回 x 的伽瑪函數值。

定義域：(-INFINITY, INFINITY]，排除負整數。
範圍：[-無窮大, 無窮大]。

範例

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

相關：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 按一下切換來源

傳回 sqrt(a**2 + b**2)，這是直角三角形中，其餘兩邊長度為 a 和 b 的最長邊 c（斜邊）的長度。

a 的網域：[-INFINITY, INFINITY]。
+ab 的網域：[-INFINITY, INFINITY]。
範圍：[0, 無窮大]。

範例

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

請注意，如果任一參數為 INFINITY 或 -INFINITY，結果為 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 按一下切換來源

傳回 fraction * 2**exponent 的值。

fraction 的網域：[0.0, 1.0)。
exponent 的網域：[0, 1024]（較大的值等於 1024）。

請參閱 IEEE 754 雙精度二進制浮點數格式：binary64。

範例

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

相關：Math.frexp（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 或 1] 按一下切換來源

傳回等於下列的 2 元素陣列

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

請參閱對數伽瑪函數。

網域：(-INFINITY, INFINITY]。
Range 的第一個元素：(-INFINITY, INFINITY]。
第二個元素為 -1 或 1。

範例

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]

相關：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 按一下切換來源

傳回 x 的底數 base 對數。

網域：[0, INFINITY]。
範圍：[-INFINITY, INFINITY)]。

範例

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 按一下切換來源

傳回 x 的底數 10 對數。

網域：[0, INFINITY]。
範圍：[-無窮大, 無窮大]。

範例

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 按一下切換來源

傳回 x 的底數 2 對數。

網域：[0, INFINITY]。
範圍：[-無窮大, 無窮大]。

範例

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 按一下以切換來源

傳回 x 的正弦，單位為弧度。

定義域：(-INFINITY, INFINITY)。
值域：[-1.0, 1.0]。

範例

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 按一下以切換來源

傳回 x 的雙曲正弦，單位為弧度。

網域：[-無窮大, 無窮大]。
範圍：[-無窮大, 無窮大]。

範例

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 按一下以切換來源

傳回 x 的主值（非負）平方根。

網域：[0, INFINITY]。
範圍：[0, 無窮大]。

範例

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 按一下以切換來源

傳回 x 的正切，單位為弧度。

定義域：(-INFINITY, INFINITY)。
範圍：(-INFINITY, INFINITY)。

範例

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 按一下以切換來源

傳回 x 的雙曲正切，單位為弧度。

網域：[-無窮大, 無窮大]。
值域：[-1, 1]。

範例

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)));
}