diff --git a/ChangeLog b/ChangeLog index f8a402f43a..e5e552fbbe 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Mon May 20 07:27:41 2013 Zachary Scott + + * math.c: RDoc formatting of Math core docs with domains and codomains + Patch by @eLobato [Fixes GH-309] + Mon May 20 05:58:12 2013 Zachary Scott * ext/bigdecimal/bigdecimal.c: Formatting for BigMath [Fixes GH-306] diff --git a/math.c b/math.c index 96bd1e9f73..2017e43d91 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 y and x. 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 x (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 x (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 x (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 x. 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}. + * Computes the arc sine of +x+. Returns -PI/2..PI/2. + * + * Domain: [-1, -1] + * + * 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 +x+. 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 x (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 x (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 x (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 x. */ 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 x. */ 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 x. */ 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 numeric. + * 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 numeric. + * Returns the base 2 logarithm of +x+. + * + * Domain: (0, INFINITY) + * + * 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 numeric. + * 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 numeric. + * Returns the non-negative square root of +x+. + * + * 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 numeric. + * 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 - * Float) and exponent (a Fixnum) of - * numeric. + * 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 flt*(2**int). + * 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 x and y. + * 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 Math module contains module functions for basic + * The Math module contains module functions for basic * trigonometric and transcendental functions. See class - * Float 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)));