From 110ab1aaf4b0055027b86ff564b66a47e0f37b58 Mon Sep 17 00:00:00 2001
From: Alan Donovan <adonovan@google.com>
Date: Fri, 20 Dec 2024 09:28:55 -0500
Subject: [PATCH] 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>
---
 src/slices/slices.go | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/slices/slices.go b/src/slices/slices.go
index 40b4d088b06e39..32029cd8ed297c 100644
--- 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...)