math: document special-cases behavior for Dim, Max and Min

Max returns +Inf if x or y is +Inf; else it returns NaN if either x or y is NaN. Max(-0, -0) returns -0.
Min returns -Inf if x or y is -Inf; else it returns NaN if either x or y is NaN. Min(+0, -0) returns -0.
Dim(+Inf, +Inf) = NaN, Dim(-Inf, -Inf) = NaN and Dim(NaN, anything) = NaN.
Also, change "conditions" to "cases" for Sin (missed it in previous CL).

R=rsc, dave
CC=golang-dev
http://codereview.appspot.com/5437137

Committer: Russ Cox <rsc@golang.org>

1 files changed, 45 insertions, 4 deletions

diff --git a/src/pkg/math/dim.go b/src/pkg/math/dim.go
index d2eb52f3b..5701b1417 100644
--- a/src/pkg/math/dim.go
+++ b/src/pkg/math/dim.go
@@ -5,15 +5,37 @@
 package math
 
 // Dim returns the maximum of x-y or 0.
+//
+// Special cases are:
+//	Dim(+Inf, +Inf) = NaN
+//	Dim(-Inf, -Inf) = NaN
+//	Dim(x, NaN) = Dim(NaN, x) = NaN
 func Dim(x, y float64) float64 {
-	if x > y {
-		return x - y
-	}
-	return 0
+	return Max(x-y, 0)
 }
 
 // Max returns the larger of x or y.
+//
+// Special cases are:
+//	Max(x, +Inf) = Max(+Inf, x) = +Inf
+//	Max(x, NaN) = Max(NaN, x) = NaN
+//	Max(+0, ±0) = Max(±0, +0) = +0
+//	Max(-0, -0) = -0
 func Max(x, y float64) float64 {
+	// TODO(rsc): Remove manual inlining of IsNaN, IsInf
+	// when compiler does it for us
+	// special cases
+	switch {
+	case x > MaxFloat64 || y > MaxFloat64: // IsInf(x, 1) || IsInf(y, 1):
+		return Inf(1)
+	case x != x || y != y: // IsNaN(x) || IsNaN(y):
+		return NaN()
+	case x == 0 && x == y:
+		if Signbit(x) {
+			return y
+		}
+		return x
+	}
 	if x > y {
 		return x
 	}
@@ -21,7 +43,26 @@ func Max(x, y float64) float64 {
 }
 
 // Min returns the smaller of x or y.
+//
+// Special cases are:
+//	Min(x, -Inf) = Min(-Inf, x) = -Inf
+//	Min(x, NaN) = Min(NaN, x) = NaN
+//	Min(-0, ±0) = Min(±0, -0) = -0
 func Min(x, y float64) float64 {
+	// TODO(rsc): Remove manual inlining of IsNaN, IsInf
+	// when compiler does it for us
+	// special cases
+	switch {
+	case x < -MaxFloat64 || y < -MaxFloat64: // IsInf(x, -1) || IsInf(y, -1):
+		return Inf(-1)
+	case x != x || y != y: // IsNaN(x) || IsNaN(y):
+		return NaN()
+	case x == 0 && x == y:
+		if Signbit(x) {
+			return x
+		}
+		return y
+	}
 	if x < y {
 		return x
 	}