bytes, strings: align requirements for functions passed to FieldFuncs

golang.org/cl/229763 removed the documentation of requirements of
the function passed to FieldsFunc. The current implementation does
not require functions to return consistent results but this had not
been the case for previous implementations.

Add the requirement for consistent results back to the documentation
to allow for future implementations to be more allocation efficient
for an output with more than 32 fields. This is possible with a two
pass algorithm first determining the number of fields used to allocate
the output slice and then splitting the input into fields.

While at it align the documentation of bytes.FieldsFunc with
strings.FieldFunc.

Fixes #38630

Change-Id: Iabbf9ca3dff0daa41f4ec930a21a3dd98e19f122
Reviewed-on: https://go-review.googlesource.com/c/go/+/230797
Run-TryBot: Martin Möhrmann <moehrmann@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@golang.org>

diff --git a/src/bytes/bytes.go b/src/bytes/bytes.go
index 0dce6af2265cff9fa5120708bcc7a41210d963f5..16d1854c44e82feb57d2a1a969b1378d33e7c2b3 100644 (file)
--- a/src/bytes/bytes.go
+++ b/src/bytes/bytes.go
@@ -445,8 +445,9 @@ func Fields(s []byte) [][]byte {
 // 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.
-// FieldsFunc makes no guarantees about the order in which it calls f(c).
-// If f does not return consistent results for a given c, FieldsFunc may crash.
+//
+// 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.
 func FieldsFunc(s []byte, f func(rune) bool) [][]byte {
        // A span is used to record a slice of s of the form s[start:end].
        // The start index is inclusive and the end index is exclusive.

diff --git a/src/strings/strings.go b/src/strings/strings.go
index 88fbeecc6f2c95213978d07b9cf01f33f25a2a14..d6f5cea6e69409c03945fe9a761d8da04137ddb3 100644 (file)
--- a/src/strings/strings.go
+++ b/src/strings/strings.go
@@ -369,6 +369,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.
+//
+// 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.
 func FieldsFunc(s string, f func(rune) bool) []string {
        // A span is used to record a slice of s of the form s[start:end].
        // The start index is inclusive and the end index is exclusive.