strings, bytes: divergent documentation for FieldsFunc functions

[kprav33n]

What version of Go are you using (go version)?

$ go version
go version go1.14.2 linux/amd64

Does this issue reproduce with the latest release?

Yes

What did you do?

Read the documentation for strings.FieldsFunc

What did you see?

I see that the documentation is out of date with respect to the following note.

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.

This was appropriate when FieldsForFunc was using a two-pass logic. However, when the function was optimized to address #19789, this note is not correct anymore. The new implementation does only one-pass over the input. Hence, we can safely remove this note.

[gopherbot]

Change https://golang.org/cl/229763 mentions this issue: strings: remove an obsolete doc note for FieldsFunc

[martisch]

Some context why I left that requirement in when I changed to code to not do two passes:

This allows us to move to a two pass algorithm when lots of Fields are involved. This would be an optimization that would improve the current code by reducing allocations when the output has more than 32 Fields. I understand that since the current implementation will not crash and the optimization would still break code that didnt adhere to the comment so might invalidate the possibilty to change the code again even with the comment.

I would like to keep the part that the function used should return consistent results to allow for a two pass algorithm. Would that be ok before we ship go1.15 and cant go back anymore?

At least we should align the comment for bytes.FieldsFunc now that we changed strings.FieldsFunc.

go/src/bytes/bytes.go

Line 448 in a9f8f02

// FieldsFunc makes no guarantees about the order in which it calls f(c).

I will send a change to align the comments again and remove the part about crashing.

[gopherbot]

Change https://golang.org/cl/230797 mentions this issue: bytes, strings: align requirements for functions passed to FieldFuncs