bytes, strings: document that FieldsFunc f must not be stateful

Fixes #8738.

LGTM=adg
R=golang-codereviews, adg
CC=golang-codereviews
https://golang.org/cl/143260045

diff --git a/src/bytes/bytes.go b/src/bytes/bytes.go
index 34c22bbfb1df12dafb5da95bbd88628341bfb6ca..7634707b3cb6e65e4d66cd7a5f295c0d476683c0 100644 (file)
--- a/src/bytes/bytes.go
+++ b/src/bytes/bytes.go
@@ -267,6 +267,8 @@ 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.
 func FieldsFunc(s []byte, f func(rune) bool) [][]byte {
        n := 0
        inField := false

diff --git a/src/strings/strings.go b/src/strings/strings.go
index 761f32a0681f2e008853995691553493f01e70cd..1b9df2e757fa1044febe8f2b92b56b08fda90166 100644 (file)
--- a/src/strings/strings.go
+++ b/src/strings/strings.go
@@ -347,6 +347,8 @@ 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).
+// If f does not return consistent results for a given c, FieldsFunc may crash.
 func FieldsFunc(s string, f func(rune) bool) []string {
        // First count the fields.
        n := 0