builtin: document when len and cap are constant
The rules are subtle, but under some circumstances the result
can be constant. Mention this and refer to the appropriate
section of the specification.
Fixes #27588.
Change-Id: I4beaad036db87501378fb2ef48d216742d096933
Reviewed-on: https://go-review.googlesource.com/135519
Reviewed-by: Robert Griesemer <gri@golang.org>
diff --git a/src/builtin/builtin.go b/src/builtin/builtin.go
index 4578c85..c78fe09 100644
--- a/src/builtin/builtin.go
+++ b/src/builtin/builtin.go
@@ -152,6 +152,9 @@
// String: the number of bytes in v.
// Channel: the number of elements queued (unread) in the channel buffer;
// if v is nil, len(v) is zero.
+// For some arguments, such as a string literal or a simple array expression, the
+// result can be a constant. See the Go language specification's "Length and
+// capacity" section for details.
func len(v Type) int
// The cap built-in function returns the capacity of v, according to its type:
@@ -161,6 +164,9 @@
// if v is nil, cap(v) is zero.
// Channel: the channel buffer capacity, in units of elements;
// if v is nil, cap(v) is zero.
+// For some arguments, such as a simple array expression, the result can be a
+// constant. See the Go language specification's "Length and capacity" section for
+// details.
func cap(v Type) int
// The make built-in function allocates and initializes an object of type
