From: Robert Griesemer Date: Wed, 24 May 2023 20:23:14 +0000 (-0700) Subject: spec: document min and max built-ins X-Git-Tag: go1.21rc1~223 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=f9d114d0e85eba7a79b9656aa65f0ba939787fb6;p=gostls13.git spec: document min and max built-ins For #59488. Change-Id: I50f65216bf02b42c1e0619702833f4a6dbed8925 Reviewed-on: https://go-review.googlesource.com/c/go/+/498136 Reviewed-by: Rob Pike Reviewed-by: Robert Griesemer Reviewed-by: Ian Lance Taylor Reviewed-by: Matthew Dempsky TryBot-Bypass: Robert Griesemer --- diff --git a/doc/go_spec.html b/doc/go_spec.html index 3f24b53f7f..2caf274ed0 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ @@ -643,6 +643,7 @@ an identifier denoting a constant, a constant expression, a conversion with a result that is a constant, or the result value of some built-in functions such as +min or max applied to constant arguments, unsafe.Sizeof applied to certain values, cap or len applied to some expressions, @@ -2319,7 +2320,7 @@ Zero value: Functions: append cap clear close complex copy delete imag len - make new panic print println real recover + make max min new panic print println real recover

Exported identifiers

@@ -7531,6 +7532,70 @@ The precise behavior is implementation-dependent.

+

Min and max

+ +

+The built-in functions min and max compute the +smallest—or largest, respectively—value of a fixed number of +arguments of ordered types. +There must be at least one argument. +

+ +

+The same type rules as for operators apply: +for ordered arguments x and +y, min(x, y) is valid if x + y is valid, +and the type of min(x, y) is the type of x + y +(and similarly for max). +If all arguments are constant, the result is constant. +

+ +
+var x, y int
+m := min(x)                 // m == x
+m := min(x, y)              // m is the smaller of x and y
+m := max(x, y, 10)          // m is the larger of x and y but at least 10
+c := max(1, 2.0, 10)        // c == 10.0 (floating-point kind)
+f := max(0, float32(x))     // type of f is float32
+var s []string
+_ = min(s...)               // invalid: slice arguments are not permitted
+t := max("", "foo", "bar")  // t == "foo" (string kind)
+
+ +

+For numeric arguments, min and max are +commutative and associative: +

+ +
+min(x, y)    == min(y, x)
+min(x, y, z) == min(min(x, y), z) == min(x, min(y, z))
+
+ +

+For floating-point arguments negative zero, NaN, and infinity the following rules apply: +

+ +
+   x        y    min(x, y)    max(x, y)
+
+  -0.0    0.0         -0.0          0.0    // negative zero is smaller than (non-negative) zero
+  -Inf      y         -Inf            y    // negative infinity is smaller than any other number
+  +Inf      y            y         +Inf    // positive infinity is larger than any other number
+   NaN      y          NaN          NaN    // if any argument is a NaN, the result is a NaN
+
+ +

+For string arguments the result for min is the first argument +with the smallest (or for max, largest) value, +compared lexically byte-wise: +

+ +
+min(x, y)    == if x <= y then x else y
+min(x, y, z) == min(min(x, y), z)
+
+

Allocation