bytes,strings: document Fields trimming of leading and trailing characters

Fixes #72841

Change-Id: I46875c61e3147c69da759bf4bf4f0539cbd4f437
Reviewed-on: https://go-review.googlesource.com/c/go/+/658218
Reviewed-by: Alan Donovan <adonovan@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/bytes/bytes.go b/src/bytes/bytes.go
index 4a2c9eac574b60b6dd5d5303748e1a41924078b0..4bc375df192ce441c898fa04108e6dbe744dc02e 100644 (file)
--- a/src/bytes/bytes.go
+++ b/src/bytes/bytes.go
@@ -451,7 +451,9 @@ var asciiSpace = [256]uint8{'\t': 1, '\n': 1, '\v': 1, '\f': 1, '\r': 1, ' ': 1}
 // Fields interprets s as a sequence of UTF-8-encoded code points.
 // It splits the slice s around each instance of one or more consecutive white space
 // characters, as defined by [unicode.IsSpace], returning a slice of subslices of s or an
-// empty slice if s contains only white space.
+// empty slice if s contains only white space. Every element of the returned slice is
+// non-empty. Unlike [Split], leading and trailing runs of white space characters
+// are discarded.
 func Fields(s []byte) [][]byte {
        // First count the fields.
        // This is an exact count if s is ASCII, otherwise it is an approximation.
@@ -505,7 +507,9 @@ func Fields(s []byte) [][]byte {
 // FieldsFunc interprets s as a sequence of UTF-8-encoded code points.
 // It splits the slice s at each run of code points c satisfying f(c) and
 // returns a slice of subslices of s. If all code points in s satisfy f(c), or
-// len(s) == 0, an empty slice is returned.
+// len(s) == 0, an empty slice is returned. Every element of the returned slice is
+// non-empty. Unlike [SplitFunc], leading and trailing runs of code points
+// satisfying f(c) are discarded.
 //
 // FieldsFunc makes no guarantees about the order in which it calls f(c)
 // and assumes that f always returns the same value for a given c.

diff --git a/src/strings/strings.go b/src/strings/strings.go
index 7eb2de635c3b3c7a2307553aa06da94a9ecac485..fb53b59f2ce735a121363a8f80a8b4b4fa639f1f 100644 (file)
--- a/src/strings/strings.go
+++ b/src/strings/strings.go
@@ -378,7 +378,9 @@ var asciiSpace = [256]uint8{'\t': 1, '\n': 1, '\v': 1, '\f': 1, '\r': 1, ' ': 1}
 
 // Fields splits the string s around each instance of one or more consecutive white space
 // characters, as defined by [unicode.IsSpace], returning a slice of substrings of s or an
-// empty slice if s contains only white space.
+// empty slice if s contains only white space. Every element of the returned slice is
+// non-empty. Unlike [Split], leading and trailing runs runs of white space characters
+// are discarded.
 func Fields(s string) []string {
        // First count the fields.
        // This is an exact count if s is ASCII, otherwise it is an approximation.
@@ -430,7 +432,9 @@ func Fields(s string) []string {
 
 // FieldsFunc splits the string s at each run of Unicode code points c satisfying f(c)
 // and returns an array of slices of s. If all code points in s satisfy f(c) or the
-// string is empty, an empty slice is returned.
+// string is empty, an empty slice is returned. Every element of the returned slice is
+// non-empty. Unlike [SplitFunc], leading and trailing runs of code points satisfying f(c)
+// are discarded.
 //
 // FieldsFunc makes no guarantees about the order in which it calls f(c)
 // and assumes that f always returns the same value for a given c.