math: doc
R=r
DELTA=173 (74 added, 14 deleted, 85 changed)
OCL=25753
CL=25767
diff --git a/src/lib/math/asin.go b/src/lib/math/asin.go
index cd3a0b7..23c9a10 100644
--- a/src/lib/math/asin.go
+++ b/src/lib/math/asin.go
@@ -13,21 +13,18 @@
* 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 @@
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);
}
diff --git a/src/lib/math/atan.go b/src/lib/math/atan.go
index 41c1705..4b18f76 100644
--- a/src/lib/math/atan.go
+++ b/src/lib/math/atan.go
@@ -57,9 +57,11 @@
* 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);
}
diff --git a/src/lib/math/atan2.go b/src/lib/math/atan2.go
index 1dc5d32..72f2117 100644
--- a/src/lib/math/atan2.go
+++ b/src/lib/math/atan2.go
@@ -6,23 +6,23 @@
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;
}
diff --git a/src/lib/math/const.go b/src/lib/math/const.go
index 21822f9..259660f 100644
--- a/src/lib/math/const.go
+++ b/src/lib/math/const.go
@@ -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 @@
Ln10 = 2.30258509299404568401799145468436420760110148862877297603332790; // A002392
Log10E = 1/Ln10;
)
+
+// BUG(rsc): The manual should define the special cases for all of these functions.
diff --git a/src/lib/math/exp.go b/src/lib/math/exp.go
index d781c1d..a32c7e1 100644
--- a/src/lib/math/exp.go
+++ b/src/lib/math/exp.go
@@ -82,6 +82,13 @@
// 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;
diff --git a/src/lib/math/fabs.go b/src/lib/math/fabs.go
index dec9a7f..9427c57 100644
--- a/src/lib/math/fabs.go
+++ b/src/lib/math/fabs.go
@@ -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;
}
diff --git a/src/lib/math/floor.go b/src/lib/math/floor.go
index cedecd1..48a1003 100644
--- a/src/lib/math/floor.go
+++ b/src/lib/math/floor.go
@@ -6,23 +6,20 @@
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);
}
diff --git a/src/lib/math/fmod.go b/src/lib/math/fmod.go
index 75e5eec..617f540 100644
--- a/src/lib/math/fmod.go
+++ b/src/lib/math/fmod.go
@@ -10,6 +10,7 @@
* 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;
diff --git a/src/lib/math/hypot.go b/src/lib/math/hypot.go
index c0ea5a1..411f74e 100644
--- a/src/lib/math/hypot.go
+++ b/src/lib/math/hypot.go
@@ -12,6 +12,8 @@
* 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;
diff --git a/src/lib/math/log.go b/src/lib/math/log.go
index 8874216..b24175b 100644
--- a/src/lib/math/log.go
+++ b/src/lib/math/log.go
@@ -70,6 +70,13 @@
// 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 @@
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);
}
-
diff --git a/src/lib/math/pow.go b/src/lib/math/pow.go
index 929943a..920d210 100644
--- a/src/lib/math/pow.go
+++ b/src/lib/math/pow.go
@@ -6,7 +6,7 @@
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 {
diff --git a/src/lib/math/pow10.go b/src/lib/math/pow10.go
index 30e5a6e..fcdd6e0 100644
--- a/src/lib/math/pow10.go
+++ b/src/lib/math/pow10.go
@@ -15,6 +15,7 @@
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);
diff --git a/src/lib/math/runtime.go b/src/lib/math/runtime.go
index 74db44a..69d3338 100644
--- a/src/lib/math/runtime.go
+++ b/src/lib/math/runtime.go
@@ -7,14 +7,46 @@
// 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)
diff --git a/src/lib/math/sin.go b/src/lib/math/sin.go
index 9c7b39b..9fc6960 100644
--- a/src/lib/math/sin.go
+++ b/src/lib/math/sin.go
@@ -6,7 +6,7 @@
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 @@
Q2 = .9463096101538208180571257e4;
Q3 = .1326534908786136358911494e3;
)
- x := arg;
if(x < 0) {
x = -x;
quad = quad+2;
@@ -52,13 +51,15 @@
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);
}
diff --git a/src/lib/math/sinh.go b/src/lib/math/sinh.go
index e79e816..ef70989 100644
--- a/src/lib/math/sinh.go
+++ b/src/lib/math/sinh.go
@@ -7,19 +7,19 @@
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 @@
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 @@
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;
}
diff --git a/src/lib/math/sqrt.go b/src/lib/math/sqrt.go
index 466b927..79384f6 100644
--- a/src/lib/math/sqrt.go
+++ b/src/lib/math/sqrt.go
@@ -13,29 +13,35 @@
* 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 @@
}
for i:=0; i<=4; i++ {
- temp = 0.5*(temp + arg/temp);
+ temp = 0.5*(temp + x/temp);
}
return temp;
}
diff --git a/src/lib/math/tan.go b/src/lib/math/tan.go
index 99155d0..2d4a044 100644
--- a/src/lib/math/tan.go
+++ b/src/lib/math/tan.go
@@ -10,7 +10,8 @@
* 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 @@
flag := false;
sign := false;
- x := arg;
if(x < 0) {
x = -x;
sign = true;
diff --git a/src/lib/math/tanh.go b/src/lib/math/tanh.go
index 2e9d74e..18d38ae 100644
--- a/src/lib/math/tanh.go
+++ b/src/lib/math/tanh.go
@@ -7,23 +7,24 @@
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);
}
