summaryrefslogtreecommitdiff
path: root/math.c
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-05-19 22:29:26 (GMT)
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-05-19 22:29:26 (GMT)
commitc1f176974c7fbbec7f5d9e178bb655deaad3dbce (patch)
tree8d2720bf5f449a3f8d4d0b37d5269bd0efdf8aad /math.c
parent2439bc9e69e57244ec7af77cc3bc899d78c3a0b4 (diff)
* math.c: RDoc formatting of Math core docs with domains and codomains
Patch by @eLobato [Fixes GH-309] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@40841 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'math.c')
-rw-r--r--math.c314
1 files changed, 218 insertions, 96 deletions
diff --git a/math.c b/math.c
index 96bd1e9..2017e43 100644
--- a/math.c
+++ b/math.c
@@ -35,10 +35,14 @@ VALUE rb_eMathDomainError;
/*
* call-seq:
- * Math.atan2(y, x) -> float
+ * Math.atan2(y, x) -> Float
*
- * Computes the arc tangent given <i>y</i> and <i>x</i>. Returns
- * -PI..PI.
+ * Computes the arc tangent given +y+ and +x+.
+ * Returns a Float in the range -PI..PI.
+ *
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: [-PI, PI]
*
* Math.atan2(-0.0, -1.0) #=> -3.141592653589793
* Math.atan2(-1.0, -1.0) #=> -2.356194490192345
@@ -77,10 +81,17 @@ math_atan2(VALUE obj, VALUE y, VALUE x)
/*
* call-seq:
- * Math.cos(x) -> float
+ * Math.cos(x) -> Float
+ *
+ * Computes the cosine of +x+ (expressed in radians).
+ * Returns a Float in the range -1.0..1.0.
+ *
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: [-1, 1]
+ *
+ * Math.cos(Math::PI) #=> -1.0
*
- * Computes the cosine of <i>x</i> (expressed in radians). Returns
- * -1..1.
*/
static VALUE
@@ -92,41 +103,61 @@ math_cos(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.sin(x) -> float
+ * Math.sin(x) -> Float
+ *
+ * Computes the cosine of +x+ (expressed in radians).
+ * Returns a Float in the range -1.0..1.0.
+ *
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: [-1, 1]
+ *
+ * Math.sin(Math::PI/2) #=> 1.0
*
- * Computes the sine of <i>x</i> (expressed in radians). Returns
- * -1..1.
*/
static VALUE
math_sin(VALUE obj, VALUE x)
{
Need_Float(x);
-
return DBL2NUM(sin(RFLOAT_VALUE(x)));
}
/*
* call-seq:
- * Math.tan(x) -> float
+ * Math.tan(x) -> Float
+ *
+ * Computes the tangent of +x+ (expressed in radians).
+ * Returns a Float in the range -1.0..1.0.
+ *
+ * Domain: n * (-PI/2, PI/2)
+ *
+ * Codomain: (−INFINITY, INFINITY)
+ *
+ * Math.tan(5 * (Math::PI/2)) #=> 3266247870639074.0
*
- * Returns the tangent of <i>x</i> (expressed in radians).
*/
static VALUE
math_tan(VALUE obj, VALUE x)
{
Need_Float(x);
-
return DBL2NUM(tan(RFLOAT_VALUE(x)));
}
/*
* call-seq:
- * Math.acos(x) -> float
+ * Math.acos(x) -> Float
+ *
+ * Computes the arc cosine of +x+. Returns 0..PI.
+ *
+ * Domain: [-1, 1]
+ *
+ * Codomain: [0, PI]
+ *
+ * Math.acos(0) == Math::PI/2 #=> true
*
- * Computes the arc cosine of <i>x</i>. Returns 0..PI.
*/
static VALUE
@@ -144,9 +175,15 @@ math_acos(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.asin(x) -> float
+ * Math.asin(x) -> Float
+ *
+ * Computes the arc sine of +x+. Returns -PI/2..PI/2.
+ *
+ * Domain: [-1, -1]
*
- * Computes the arc sine of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ * Codomain: [-PI/2, PI/2]
+ *
+ * Math.asin(1) == Math::PI/2 #=> true
*/
static VALUE
@@ -164,9 +201,15 @@ math_asin(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.atan(x) -> float
+ * Math.atan(x) -> Float
+ *
+ * Computes the arc tangent of +x+. Returns -PI/2..PI/2.
*
- * Computes the arc tangent of <i>x</i>. Returns -{PI/2} .. {PI/2}.
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: (-PI/2, PI/2)
+ *
+ * Math.atan(0) #=> 0.0
*/
static VALUE
@@ -186,16 +229,22 @@ cosh(double x)
/*
* call-seq:
- * Math.cosh(x) -> float
+ * Math.cosh(x) -> Float
+ *
+ * Computes the hyperbolic cosine of +x+ (expressed in radians).
+ *
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: [1, INFINITY)
+ *
+ * Math.cosh(0) #=> 1.0
*
- * Computes the hyperbolic cosine of <i>x</i> (expressed in radians).
*/
static VALUE
math_cosh(VALUE obj, VALUE x)
{
Need_Float(x);
-
return DBL2NUM(cosh(RFLOAT_VALUE(x)));
}
@@ -209,10 +258,16 @@ sinh(double x)
/*
* call-seq:
- * Math.sinh(x) -> float
+ * Math.sinh(x) -> Float
+ *
+ * Computes the hyperbolic sine of +x+ (expressed in radians).
+ *
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: (−INFINITY, INFINITY)
+ *
+ * Math.sinh(0) #=> 0.0
*
- * Computes the hyperbolic sine of <i>x</i> (expressed in
- * radians).
*/
static VALUE
@@ -232,10 +287,16 @@ tanh(double x)
/*
* call-seq:
- * Math.tanh() -> float
+ * Math.tanh(x) -> Float
+ *
+ * Computes the hyperbolic tangent of +x+ (expressed in radians).
+ *
+ * Domain: (−INFINITY, INFINITY)
+ *
+ * Codomain: (−1, 1)
+ *
+ * Math.tanh(0) #=> 0.0
*
- * Computes the hyperbolic tangent of <i>x</i> (expressed in
- * radians).
*/
static VALUE
@@ -247,9 +308,16 @@ math_tanh(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.acosh(x) -> float
+ * Math.acosh(x) -> Float
+ *
+ * Computes the inverse hyperbolic cosine of +x+.
+ *
+ * Domain: [1, INFINITY)
+ *
+ * Codomain: [0, INFINITY)
+ *
+ * Math.acosh(1) #=> 0.0
*
- * Computes the inverse hyperbolic cosine of <i>x</i>.
*/
static VALUE
@@ -267,9 +335,16 @@ math_acosh(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.asinh(x) -> float
+ * Math.asinh(x) -> Float
+ *
+ * Computes the inverse hyperbolic sine of +x+.
+ *
+ * Domain: (-INFINITY, INFINITY)
+ *
+ * Codomain: (-INFINITY, INFINITY)
+ *
+ * Math.asinh(1) #=> 0.881373587019543
*
- * Computes the inverse hyperbolic sine of <i>x</i>.
*/
static VALUE
@@ -281,9 +356,16 @@ math_asinh(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.atanh(x) -> float
+ * Math.atanh(x) -> Float
+ *
+ * Computes the inverse hyperbolic tangent of +x+.
+ *
+ * Domain: (-1, 1)
+ *
+ * Codomain: (-INFINITY, INFINITY)
+ *
+ * Math.atanh(1) #=> Infinity
*
- * Computes the inverse hyperbolic tangent of <i>x</i>.
*/
static VALUE
@@ -304,10 +386,14 @@ math_atanh(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.exp(x) -> float
+ * Math.exp(x) -> Float
*
* Returns e**x.
*
+ * Domain: (-INFINITY, INFINITY)
+ *
+ * Codomain: (0, INFINITY)
+ *
* Math.exp(0) #=> 1.0
* Math.exp(1) #=> 2.718281828459045
* Math.exp(1.5) #=> 4.4816890703380645
@@ -332,13 +418,17 @@ math_exp(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.log(numeric) -> float
- * Math.log(num,base) -> float
+ * Math.log(x) -> Float
+ * Math.log(num, base) -> Float
*
- * Returns the natural logarithm of <i>numeric</i>.
+ * Returns the natural logarithm of +x+.
* If additional second argument is given, it will be the base
* of logarithm.
*
+ * Domain: (0, INFINITY)
+ *
+ * Codomain: (-INFINITY, INFINITY)
+ *
* Math.log(1) #=> 0.0
* Math.log(Math::E) #=> 1.0
* Math.log(Math::E**3) #=> 3.0
@@ -381,9 +471,13 @@ extern double log2(double);
/*
* call-seq:
- * Math.log2(numeric) -> float
+ * Math.log2(x) -> Float
+ *
+ * Returns the base 2 logarithm of +x+.
+ *
+ * Domain: (0, INFINITY)
*
- * Returns the base 2 logarithm of <i>numeric</i>.
+ * Codomain: (-INFINITY, INFINITY)
*
* Math.log2(1) #=> 0.0
* Math.log2(2) #=> 1.0
@@ -409,9 +503,13 @@ math_log2(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.log10(numeric) -> float
+ * Math.log10(x) -> Float
*
- * Returns the base 10 logarithm of <i>numeric</i>.
+ * Returns the base 10 logarithm of +x+.
+ *
+ * Domain: (0, INFINITY)
+ *
+ * Codomain: (-INFINITY, INFINITY)
*
* Math.log10(1) #=> 0.0
* Math.log10(10) #=> 1.0
@@ -436,26 +534,28 @@ math_log10(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.sqrt(numeric) -> float
+ * Math.sqrt(x) -> Float
+ *
+ * Returns the non-negative square root of +x+.
*
- * Returns the non-negative square root of <i>numeric</i>.
+ * Domain: [0, INFINITY)
+ *
+ * Codomain:[0, INFINITY)
*
* 0.upto(10) {|x|
* p [x, Math.sqrt(x), Math.sqrt(x)**2]
* }
- * #=>
- * [0, 0.0, 0.0]
- * [1, 1.0, 1.0]
- * [2, 1.4142135623731, 2.0]
- * [3, 1.73205080756888, 3.0]
- * [4, 2.0, 4.0]
- * [5, 2.23606797749979, 5.0]
- * [6, 2.44948974278318, 6.0]
- * [7, 2.64575131106459, 7.0]
- * [8, 2.82842712474619, 8.0]
- * [9, 3.0, 9.0]
- * [10, 3.16227766016838, 10.0]
- *
+ * #=> [0, 0.0, 0.0]
+ * # [1, 1.0, 1.0]
+ * # [2, 1.4142135623731, 2.0]
+ * # [3, 1.73205080756888, 3.0]
+ * # [4, 2.0, 4.0]
+ * # [5, 2.23606797749979, 5.0]
+ * # [6, 2.44948974278318, 6.0]
+ * # [7, 2.64575131106459, 7.0]
+ * # [8, 2.82842712474619, 8.0]
+ * # [9, 3.0, 9.0]
+ * # [10, 3.16227766016838, 10.0]
*/
static VALUE
@@ -474,33 +574,36 @@ math_sqrt(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.cbrt(numeric) -> float
+ * Math.cbrt(x) -> Float
*
- * Returns the cube root of <i>numeric</i>.
+ * Returns the cube root of +x+.
+ *
+ * Domain: [0, INFINITY)
+ *
+ * Codomain:[0, INFINITY)
*
* -9.upto(9) {|x|
* p [x, Math.cbrt(x), Math.cbrt(x)**3]
* }
- * #=>
- * [-9, -2.0800838230519, -9.0]
- * [-8, -2.0, -8.0]
- * [-7, -1.91293118277239, -7.0]
- * [-6, -1.81712059283214, -6.0]
- * [-5, -1.7099759466767, -5.0]
- * [-4, -1.5874010519682, -4.0]
- * [-3, -1.44224957030741, -3.0]
- * [-2, -1.25992104989487, -2.0]
- * [-1, -1.0, -1.0]
- * [0, 0.0, 0.0]
- * [1, 1.0, 1.0]
- * [2, 1.25992104989487, 2.0]
- * [3, 1.44224957030741, 3.0]
- * [4, 1.5874010519682, 4.0]
- * [5, 1.7099759466767, 5.0]
- * [6, 1.81712059283214, 6.0]
- * [7, 1.91293118277239, 7.0]
- * [8, 2.0, 8.0]
- * [9, 2.0800838230519, 9.0]
+ * #=> [-9, -2.0800838230519, -9.0]
+ * # [-8, -2.0, -8.0]
+ * # [-7, -1.91293118277239, -7.0]
+ * # [-6, -1.81712059283214, -6.0]
+ * # [-5, -1.7099759466767, -5.0]
+ * # [-4, -1.5874010519682, -4.0]
+ * # [-3, -1.44224957030741, -3.0]
+ * # [-2, -1.25992104989487, -2.0]
+ * # [-1, -1.0, -1.0]
+ * # [0, 0.0, 0.0]
+ * # [1, 1.0, 1.0]
+ * # [2, 1.25992104989487, 2.0]
+ * # [3, 1.44224957030741, 3.0]
+ * # [4, 1.5874010519682, 4.0]
+ * # [5, 1.7099759466767, 5.0]
+ * # [6, 1.81712059283214, 6.0]
+ * # [7, 1.91293118277239, 7.0]
+ * # [8, 2.0, 8.0]
+ * # [9, 2.0800838230519, 9.0]
*
*/
@@ -513,11 +616,10 @@ math_cbrt(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.frexp(numeric) -> [ fraction, exponent ]
+ * Math.frexp(x) -> [fraction, exponent]
*
- * Returns a two-element array containing the normalized fraction (a
- * <code>Float</code>) and exponent (a <code>Fixnum</code>) of
- * <i>numeric</i>.
+ * Returns a two-element array containing the normalized fraction (a Float)
+ * and exponent (a Fixnum) of +x+.
*
* fraction, exponent = Math.frexp(1234) #=> [0.6025390625, 11]
* fraction * 2**exponent #=> 1234.0
@@ -537,9 +639,9 @@ math_frexp(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.ldexp(flt, int) -> float
+ * Math.ldexp(fraction, exponent) -> float
*
- * Returns the value of <i>flt</i>*(2**<i>int</i>).
+ * Returns the value of +fraction+*(2**+exponent+).
*
* fraction, exponent = Math.frexp(1234)
* Math.ldexp(fraction, exponent) #=> 1234.0
@@ -554,10 +656,10 @@ math_ldexp(VALUE obj, VALUE x, VALUE n)
/*
* call-seq:
- * Math.hypot(x, y) -> float
+ * Math.hypot(x, y) -> Float
*
- * Returns sqrt(x**2 + y**2), the hypotenuse of a right-angled triangle
- * with sides <i>x</i> and <i>y</i>.
+ * Returns sqrt(x**2 + y**2), the hypotenuse of a right-angled triangle with
+ * sides +x+ and +y+.
*
* Math.hypot(3, 4) #=> 5.0
*/
@@ -571,9 +673,16 @@ math_hypot(VALUE obj, VALUE x, VALUE y)
/*
* call-seq:
- * Math.erf(x) -> float
+ * Math.erf(x) -> Float
+ *
+ * Calculates the error function of +x+.
+ *
+ * Domain: (-INFINITY, INFINITY)
+ *
+ * Codomain: (-1, 1)
+ *
+ * Math.erf(0) #=> 0.0
*
- * Calculates the error function of x.
*/
static VALUE
@@ -585,9 +694,16 @@ math_erf(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.erfc(x) -> float
+ * Math.erfc(x) -> Float
*
* Calculates the complementary error function of x.
+ *
+ * Domain: (-INFINITY, INFINITY)
+ *
+ * Codomain: (0, 2)
+ *
+ * Math.erfc(0) #=> 1.0
+ *
*/
static VALUE
@@ -599,7 +715,7 @@ math_erfc(VALUE obj, VALUE x)
/*
* call-seq:
- * Math.gamma(x) -> float
+ * Math.gamma(x) -> Float
*
* Calculates the gamma function of x.
*
@@ -690,12 +806,14 @@ math_gamma(VALUE obj, VALUE x)
* call-seq:
* Math.lgamma(x) -> [float, -1 or 1]
*
- * Calculates the logarithmic gamma of x and
- * the sign of gamma of x.
+ * Calculates the logarithmic gamma of +x+ and the sign of gamma of +x+.
*
* Math.lgamma(x) is same as
* [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
* but avoid overflow by Math.gamma(x) for large x.
+ *
+ * Math.lgamma(0) #=> [Infinity, 1]
+ *
*/
static VALUE
@@ -767,10 +885,12 @@ exp1(sqrt)
/*
* Document-class: Math
*
- * The <code>Math</code> module contains module functions for basic
+ * The Math module contains module functions for basic
* trigonometric and transcendental functions. See class
- * <code>Float</code> for a list of constants that
+ * Float for a list of constants that
* define Ruby's floating point accuracy.
+ *
+ * Domains and codomains are given only for real (not complex) numbers.
*/
@@ -781,12 +901,14 @@ Init_Math(void)
rb_eMathDomainError = rb_define_class_under(rb_mMath, "DomainError", rb_eStandardError);
#ifdef M_PI
+ /* Definition of the mathematical constant PI as a Float number. */
rb_define_const(rb_mMath, "PI", DBL2NUM(M_PI));
#else
rb_define_const(rb_mMath, "PI", DBL2NUM(atan(1.0)*4.0));
#endif
#ifdef M_E
+ /* Definition of the mathematical constant E (e) as a Float number. */
rb_define_const(rb_mMath, "E", DBL2NUM(M_E));
#else
rb_define_const(rb_mMath, "E", DBL2NUM(exp(1.0)));