slices: document two oddities

Fixes #70935

Change-Id: Idf4a38a05ba595d616b6469a14419ff873bbd354
Reviewed-on: https://go-review.googlesource.com/c/go/+/638095
Reviewed-by: Keith Randall <khr@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Keith Randall <khr@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/slices/slices.go b/src/slices/slices.go
index 40b4d088b06e391e5684bbf28c2518551a53cda8..32029cd8ed297cb86c6d6508a786c1c658b18944 100644 (file)
--- a/src/slices/slices.go
+++ b/src/slices/slices.go
@@ -414,6 +414,7 @@ func Grow[S ~[]E, E any](s S, n int) S {
                panic("cannot be negative")
        }
        if n -= cap(s) - len(s); n > 0 {
+               // This expression allocates only once (see test).
                s = append(s[:cap(s)], make([]E, n)...)[:len(s)]
        }
        return s
@@ -483,6 +484,9 @@ func Concat[S ~[]E, E any](slices ...S) S {
                        panic("len out of range")
                }
        }
+       // Use Grow, not make, to round up to the size class:
+       // the extra space is otherwise unused and helps
+       // callers that append a few elements to the result.
        newslice := Grow[S](nil, size)
        for _, s := range slices {
                newslice = append(newslice, s...)