]> Cypherpunks repositories - gostls13.git/commitdiff
math: doc
authorRuss Cox <rsc@golang.org>
Thu, 5 Mar 2009 21:31:01 +0000 (13:31 -0800)
committerRuss Cox <rsc@golang.org>
Thu, 5 Mar 2009 21:31:01 +0000 (13:31 -0800)
R=r
DELTA=173  (74 added, 14 deleted, 85 changed)
OCL=25753
CL=25767

18 files changed:
src/lib/math/asin.go
src/lib/math/atan.go
src/lib/math/atan2.go
src/lib/math/const.go
src/lib/math/exp.go
src/lib/math/fabs.go
src/lib/math/floor.go
src/lib/math/fmod.go
src/lib/math/hypot.go
src/lib/math/log.go
src/lib/math/pow.go
src/lib/math/pow10.go
src/lib/math/runtime.go
src/lib/math/sin.go
src/lib/math/sinh.go
src/lib/math/sqrt.go
src/lib/math/tan.go
src/lib/math/tanh.go

index cd3a0b7a0f2394b0b315b9bbd6d8b96193569019..23c9a1069badabc15435d217505aa12a95e9cdc8 100644 (file)
@@ -13,21 +13,18 @@ import "math"
  * Arctan is called after appropriate range reduction.
  */
 
-func Asin(arg float64) float64 {
-       var temp, x float64;
-       var sign bool;
-
-       sign = false;
-       x = arg;
+// Asin returns the arc sine of x.
+func Asin(x float64) float64 {
+       sign := false;
        if x < 0 {
                x = -x;
                sign = true;
        }
-       if arg > 1 {
+       if x > 1 {
                return NaN();
        }
 
-       temp = Sqrt(1 - x*x);
+       temp := Sqrt(1 - x*x);
        if x > 0.7 {
                temp = Pi/2 - Atan(temp/x);
        } else {
@@ -40,9 +37,10 @@ func Asin(arg float64) float64 {
        return temp;
 }
 
-func Acos(arg float64) float64 {
-       if arg > 1 || arg < -1 {
+// Acos returns the arc cosine of x.
+func Acos(x float64) float64 {
+       if x > 1 || x < -1 {
                return NaN();
        }
-       return Pi/2 - Asin(arg);
+       return Pi/2 - Asin(x);
 }
index 41c1705e098acaf914830fba03c2fb8771d85d89..4b18f76aaf673bb5fad74c902214ef04f8ef9a38 100644 (file)
@@ -57,9 +57,11 @@ func satan(arg float64) float64 {
  *     atan makes its argument positive and
  *     calls the inner routine satan.
  */
-func Atan(arg float64) float64 {
-       if arg > 0 {
-               return satan(arg);
+
+// Atan returns the arc tangent of x.
+func Atan(x float64) float64 {
+       if x > 0 {
+               return satan(x);
        }
-       return -satan(-arg);
+       return -satan(-x);
 }
index 1dc5d325ebbf22142994a8a27fd0a421a5ec55ba..72f2117b376e3d5d852ce6b2f0738e33123789b9 100644 (file)
@@ -6,23 +6,23 @@ package math
 
 import "math"
 
-/*
- *     atan2 discovers what quadrant the angle
- *     is in and calls atan.
- */
-func Atan2(arg1, arg2 float64) float64 {
-       if arg1+arg2 == arg1 {
-               if arg1 >= 0 {
+// Atan returns the arc tangent of y/x, using
+// the signs of the two to determine the quadrant
+// of the return value.
+func Atan2(x, y float64) float64 {
+       // Determine the quadrant and call atan.
+       if x+y == x {
+               if x >= 0 {
                        return Pi/2;
                }
                return -Pi/2;
        }
-       x := Atan(arg1/arg2);
-       if arg2 < 0 {
-               if x <= 0 {
-                       return x + Pi;
+       q := Atan(x/y);
+       if y < 0 {
+               if q <= 0 {
+                       return q + Pi;
                }
-               return x - Pi;
+               return q - Pi;
        }
-       return x;
+       return q;
 }
index 21822f90ad307867a2e71e6a5793ac24c28e4bbf..259660fea6945dc370cacf2eea393250b8c5b7f9 100644 (file)
@@ -2,12 +2,12 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// The math package provides basic constants and mathematical functions.
 package math
 
+// Mathematical constants.
+// Reference: http://www.research.att.com/~njas/sequences/Axxxxxx
 const (
-       // Mathematical constants.
-       // Reference: http://www.research.att.com/~njas/sequences/Axxxxxx
-
        E       = 2.71828182845904523536028747135266249775724709369995957496696763;  // A001113
        Pi      = 3.14159265358979323846264338327950288419716939937510582097494459;  // A000796
        Phi     = 1.61803398874989484820458683436563811772030917980576286213544862;  // A001622
@@ -22,3 +22,5 @@ const (
        Ln10    = 2.30258509299404568401799145468436420760110148862877297603332790;  // A002392
        Log10E  = 1/Ln10;
 )
+
+// BUG(rsc): The manual should define the special cases for all of these functions.
index d781c1dec09ab6cecd391c1314525a5f125849c9..a32c7e1d50c96703890ace2570f660e727d26563 100644 (file)
@@ -82,6 +82,13 @@ import "math"
 // compiler will convert from decimal to binary accurately enough
 // to produce the hexadecimal values shown.
 
+// Exp returns e^x, the base-e exponential of x.
+//
+// Special cases are:
+//     Exp(+Inf) = +Inf
+//     Exp(NaN) = NaN
+// Very large values overflow to -Inf or +Inf.
+// Very small values underflow to 1.
 func Exp(x float64) float64 {
        const (
                Ln2Hi   = 6.93147180369123816490e-01;
index dec9a7feb79456e589731978f6882932ee9e1367..9427c5726248a1f219f4011ab4ac31cc780905c8 100644 (file)
@@ -4,10 +4,11 @@
 
 package math
 
-func Fabs(arg float64) float64 {
-       if arg < 0 {
-               return -arg;
+// Fabs returns the absolute value of x.
+func Fabs(x float64) float64 {
+       if x < 0 {
+               return -x;
        }
-       return arg;
+       return x;
 }
 
index cedecd1f6ca22dcef2a1e5bd8c82af100869fba6..48a1003f044b1ad2cac1bff92d3529ecdbcbca40 100644 (file)
@@ -6,23 +6,20 @@ package math
 
 import "math"
 
-/*
- * floor and ceil-- greatest integer <= arg
- * (resp least >=)
- */
-
-func Floor(arg float64) float64 {
-       if arg < 0 {
-               d, fract := Modf(-arg);
+// Floor returns the greatest integer value less than or equal to x.
+func Floor(x float64) float64 {
+       if x < 0 {
+               d, fract := Modf(-x);
                if fract != 0.0 {
                        d = d+1;
                }
                return -d;
        }
-       d, fract := Modf(arg);
+       d, fract := Modf(x);
        return d;
 }
 
-func Ceil(arg float64) float64 {
-       return -Floor(-arg);
+// Ceil returns the least integer value greater than or equal to x.
+func Ceil(x float64) float64 {
+       return -Floor(-x);
 }
index 75e5eece2dbfe9c54944dd55d29bc5fd47560be9..617f5408bbad1d66e1280082adb854125a6b37e4 100644 (file)
@@ -10,6 +10,7 @@ import "math"
  *     floating-point mod func without infinity or NaN checking
  */
 
+// Fmod returns the floating-point remainder of x/y.
 func Fmod(x, y float64) float64 {
        if y == 0 {
                return x;
index c0ea5a1f79f8f9485f3a85545148ce40ce589451..411f74e4ff73c98cb853a6ca924cdfefe644d55a 100644 (file)
@@ -12,6 +12,8 @@ package math
  *     Vol. 27, Number 6, pp. 577-581, Nov. 1983
  */
 
+// Hypot computes Sqrt(p*p + q*q), taking care to avoid
+// unnecessary overflow and underflow.
 func Hypot(p, q float64) float64 {
        if p < 0 {
                p = -p;
index 8874216427ae047c24b42e5de226c3ffc4788468..b24175b6394412aa36a4b95a6ac3cc60f0d0e853 100644 (file)
@@ -70,6 +70,13 @@ import "math"
 // compiler will convert from decimal to binary accurately enough
 // to produce the hexadecimal values shown.
 
+// Log returns the natural logarithm of x.
+//
+// Special cases are:
+//     Log(+Inf) = +Inf
+//     Log(0) = -Inf
+//     Log(x < 0) = NaN
+//     Log(NaN) = NaN
 func Log(x float64) float64 {
        const (
                Ln2Hi = 6.93147180369123816490e-01;     /* 3fe62e42 fee00000 */
@@ -113,11 +120,12 @@ func Log(x float64) float64 {
        return k*Ln2Hi - ((hfsq-(s*(hfsq+R)+k*Ln2Lo)) - f);
 }
 
-func Log10(arg float64) float64 {
-       if arg <= 0 {
+// Log10 returns the decimal logarthm of x.
+// The special cases are the same as for Log.
+func Log10(x float64) float64 {
+       if x <= 0 {
                return NaN();
        }
-       return Log(arg) * (1/Ln10);
+       return Log(x) * (1/Ln10);
 }
 
-
index 929943a13039834b6f77a6e375dc8f1be724b95f..920d210b56dc6a90ffe87bac9943c021a3374a2b 100644 (file)
@@ -6,7 +6,7 @@ package math
 
 import "math"
 
-// x^y: exponentiation
+// Pow returns x**y, the base-x exponential of y.
 func Pow(x, y float64) float64 {
        // TODO: x or y NaN, ±Inf, maybe ±0.
        switch {
index 30e5a6ee5518f597c4328589a397eb0c30efe6db..fcdd6e0a1133802792d2e7089ce326293f35fac8 100644 (file)
@@ -15,6 +15,7 @@ package math
 
 var    pow10tab        [70]float64;
 
+// Pow10 returns 10**x, the base-10 exponential of x.
 func Pow10(e int) float64 {
        if e < 0 {
                return 1/Pow10(-e);
index 74db44a9542f69dc61f3b22d208485ea95e3aa26..69d333825bf611dcbd9eb6a5208d186626554707 100644 (file)
@@ -7,14 +7,46 @@ package math
 // implemented in C, in ../../runtime
 // perhaps one day the implementations will move here.
 
-func Float32bits(f float32) (b uint32) 
-func Float32frombits(b uint32) (f float32) 
-func Float64bits(f float64) (b uint64) 
-func Float64frombits(b uint64) (f float64) 
-func Frexp(f float64) (frac float64, exp int) 
-func Inf(sign int32) (f float64) 
-func IsInf(f float64, sign int) (is bool) 
-func IsNaN(f float64) (is bool) 
-func Ldexp(frac float64, exp int) (f float64) 
-func Modf(f float64) (integer float64, frac float64) 
-func NaN() (f float64) 
+// Float32bits returns the IEEE 754 binary representation of f.
+func Float32bits(f float32) (b uint32)
+
+// Float32frombits returns the floating point number corresponding
+// to the IEEE 754 binary representation b.
+func Float32frombits(b uint32) (f float32)
+
+// Float64bits returns the IEEE 754 binary representation of f.
+func Float64bits(f float64) (b uint64)
+
+// Float64frombits returns the floating point number corresponding
+// the IEEE 754 binary representation b.
+func Float64frombits(b uint64) (f float64)
+
+// Frexp breaks f into a normalized fraction
+// and an integral power of two.
+// It returns frac and exp satisfying f == frac × 2<sup>exp</sup>,
+// with the absolute value of frac in the interval [½, 1).
+func Frexp(f float64) (frac float64, exp int)
+
+// Inf returns positive infinity if sign >= 0, negative infinity if sign < 0.
+func Inf(sign int32) (f float64)
+
+// IsInf returns whether f is an infinity, according to sign.
+// If sign > 0, IsInf returns whether f is positive infinity.
+// If sign < 0, IsInf returns whether f is negative infinity.
+// If sign == 0, IsInf returns whether f is either infinity.
+func IsInf(f float64, sign int) (is bool)
+
+// IsNaN returns whether f is an IEEE 754 ``not-a-number'' value.
+func IsNaN(f float64) (is bool)
+
+// Ldexp is the inverse of Frexp.
+// It returns frac × 2<sup>exp</sup>.
+func Ldexp(frac float64, exp int) (f float64)
+
+// Modf returns integer and fractional floating-point numbers
+// that sum to f.
+// Integer and frac have the same sign as f.
+func Modf(f float64) (integer float64, frac float64)
+
+// NaN returns an IEEE 754 ``not-a-number'' value.
+func NaN() (f float64)
index 9c7b39bf82e8e7b4497d054555c352c1e4873c49..9fc69606cd43d3959d517f15e013ed40bb84db65 100644 (file)
@@ -6,7 +6,7 @@ package math
 
 import "math"
 
-func sinus(arg float64, quad int) float64 {
+func sinus(x float64, quad int) float64 {
        // Coefficients are #3370 from Hart & Cheney (18.80D).
        const
        (
@@ -20,7 +20,6 @@ func sinus(arg float64, quad int) float64 {
                Q2      =  .9463096101538208180571257e4;
                Q3      =  .1326534908786136358911494e3;
        )
-       x := arg;
        if(x < 0) {
                x = -x;
                quad = quad+2;
@@ -52,13 +51,15 @@ func sinus(arg float64, quad int) float64 {
        return temp1/temp2;
 }
 
-func Cos(arg float64) float64 {
-       if arg < 0 {
-               arg = -arg;
+// Cos returns the cosine of x.
+func Cos(x float64) float64 {
+       if x < 0 {
+               x = -x;
        }
-       return sinus(arg, 1);
+       return sinus(x, 1);
 }
 
-func Sin(arg float64) float64 {
-       return sinus(arg, 0);
+// Sin returns the sine of x.
+func Sin(x float64) float64 {
+       return sinus(x, 0);
 }
index e79e8161bcbcb8c559c39fffedbd7e8eaad616b5..ef70989fb902630b8e74e425cfa4340050c6c245 100644 (file)
@@ -7,19 +7,19 @@ package math
 import "math"
 
 /*
- *     sinh(arg) returns the hyperbolic sine of its floating-
- *     point argument.
+ *     Sinh(x) returns the hyperbolic sine of x
  *
  *     The exponential func is called for arguments
  *     greater in magnitude than 0.5.
  *
  *     A series is used for arguments smaller in magnitude than 0.5.
  *
- *     cosh(arg) is computed from the exponential func for
+ *     Cosh(x) is computed from the exponential func for
  *     all arguments.
  */
 
-func Sinh(arg float64) float64 {
+// Sinh returns the hyperbolic sine of x.
+func Sinh(x float64) float64 {
        // The coefficients are #2029 from Hart & Cheney. (20.36D)
        const
        (
@@ -32,23 +32,23 @@ func Sinh(arg float64) float64 {
                Q2      = -0.173678953558233699533450911e+3;
        )
 
-               sign := false;
-       if arg < 0 {
-               arg = -arg;
+       sign := false;
+       if x < 0 {
+               x = -x;
                sign = true;
        }
 
        var temp float64;
        switch true {
-       case arg > 21:
-               temp = Exp(arg)/2;
+       case x > 21:
+               temp = Exp(x)/2;
 
-       case arg > 0.5:
-               temp = (Exp(arg) - Exp(-arg))/2;
+       case x > 0.5:
+               temp = (Exp(x) - Exp(-x))/2;
 
        default:
-               sq := arg*arg;
-               temp = (((P3*sq+P2)*sq+P1)*sq+P0)*arg;
+               sq := x*x;
+               temp = (((P3*sq+P2)*sq+P1)*sq+P0)*x;
                temp = temp/(((sq+Q2)*sq+Q1)*sq+Q0);
        }
 
@@ -58,12 +58,13 @@ func Sinh(arg float64) float64 {
        return temp;
 }
 
-func Cosh(arg float64) float64 {
-       if arg < 0 {
-               arg = - arg;
+// Cosh returns the hyperbolic cosine of x.
+func Cosh(x float64) float64 {
+       if x < 0 {
+               x = - x;
        }
-       if arg > 21 {
-               return Exp(arg)/2;
+       if x > 21 {
+               return Exp(x)/2;
        }
-       return (Exp(arg) + Exp(-arg))/2;
+       return (Exp(x) + Exp(-x))/2;
 }
index 466b927715fdf021cb6059fb58ebe95f76999a4f..79384f6481a593782f1e40e2c473af91abc36e59 100644 (file)
@@ -13,29 +13,35 @@ import "math"
  *     calls frexp
  */
 
-func Sqrt(arg float64) float64 {
-       if IsInf(arg, 1) {
-               return arg;
+// Sqrt returns the square root of x.
+//
+// Special cases are:
+//     Sqrt(+Inf) = +Inf
+//     Sqrt(0) = 0
+//     Sqrt(x < 0) = NaN
+func Sqrt(x float64) float64 {
+       if IsInf(x, 1) {
+               return x;
        }
 
-       if arg <= 0 {
-               if arg < 0 {
+       if x <= 0 {
+               if x < 0 {
                        return NaN();
                }
                return 0;
        }
 
-       x,exp := Frexp(arg);
-       for x < 0.5 {
-               x = x*2;
+       y, exp := Frexp(x);
+       for y < 0.5 {
+               y = y*2;
                exp = exp-1;
        }
 
        if exp&1 != 0 {
-               x = x*2;
+               y = y*2;
                exp = exp-1;
        }
-       temp := 0.5 * (1+x);
+       temp := 0.5 * (1+y);
 
        for exp > 60 {
                temp = temp * float64(1<<30);
@@ -54,7 +60,7 @@ func Sqrt(arg float64) float64 {
        }
 
        for i:=0; i<=4; i++ {
-               temp = 0.5*(temp + arg/temp);
+               temp = 0.5*(temp + x/temp);
        }
        return temp;
 }
index 99155d0053691178e35b918b23f32b9a06bd9470..2d4a044b87d2233b7c7eceb1d51f6d7ad41b2c96 100644 (file)
@@ -10,7 +10,8 @@ import "math"
  *     floating point tangent
  */
 
-func Tan(arg float64) float64 {
+// Tan returns the tangent of x.
+func Tan(x float64) float64 {
        // Coefficients are #4285 from Hart & Cheney. (19.74D)
        const
        (
@@ -26,7 +27,6 @@ func Tan(arg float64) float64 {
 
        flag := false;
        sign := false;
-       x := arg;
        if(x < 0) {
                x = -x;
                sign = true;
index 2e9d74ee4b1a38d73c956fc97d5a759f338a34a4..18d38ae8fece7ca946ef70a0445ff8d83d2c0e1e 100644 (file)
@@ -7,23 +7,24 @@ package math
 import "math"
 
 /*
- *     tanh(arg) computes the hyperbolic tangent of its floating
+ *     tanh(x) computes the hyperbolic tangent of its floating
  *     point argument.
  *
  *     sinh and cosh are called except for large arguments, which
  *     would cause overflow improperly.
  */
 
-func Tanh(arg float64) float64 {
-       if arg < 0 {
-               arg = -arg;
-               if arg > 21 {
+// Tanh computes the hyperbolic tangent of x.
+func Tanh(x float64) float64 {
+       if x < 0 {
+               x = -x;
+               if x > 21 {
                        return -1;
                }
-               return -Sinh(arg)/Cosh(arg);
+               return -Sinh(x)/Cosh(x);
        }
-       if arg > 21 {
+       if x > 21 {
                return 1;
        }
-       return Sinh(arg)/Cosh(arg);
+       return Sinh(x)/Cosh(x);
 }