strings: document that order of pairs matters in NewReplacer

[pam4]

The current documentation doesn't specify the result of the following code (could be either "declare" or "decodel") because they both match at the same starting position:

strings.NewReplacer("decl", "declare", "dec", "decode").Replace("decl")

The actual result is "declare", i.e. the first pair takes precedence (not the longest old string).
I just run into a use case that would require this precedence to be guaranteed, but I can't rely on it because it's not documented.

Looking at the code I presume the precedence is intentional: the generic algorithm uses a lookup trie for prioritized key/value pairs, and keys are added with decreasing priority, see here (len(oldnew)-i is the priority).

Unless there is actually a reason for it to be left undefined, I propose something like:

Leftmost matches take precedence, and among those, the leftmost pair in NewReplacer's arguments takes precedence.

Ok, hopefully someone will come up with better words...

[rentziass]

Leftmost matches take precedence, and among those, the leftmost pair in NewReplacer's arguments takes precedence.

I think this is clear. Maybe

Leftmost matches take precedence, and among those, the leftmost matching pair in NewReplacer's arguments takes precedence.

But maybe that's obvious 🤔

[pam4]

Thanks for your insight.

I find a little confusing that the first "leftmost" is relative to the target string while the second is relative to the order of the arguments, so maybe we should get rid of the latter:

Leftmost matches take precedence, and among those, the matching pair appearing earlier in NewReplacer's arguments takes precedence.

But I'm not sure how integrate the "non overlapping" part. Here's another try:

The leftmost match in the target string is replaced first. If more than one match is possible at the same starting position, the matching pair appearing earlier in NewReplacer's arguments is used. Then the search is repeated on the remaining substring and so on, without overlapping matches.

[rentziass]

@pam4 I like this one! How about this? Sounds maybe a little simpler to me

When multiple matches are found at the same starting position, the matching pair appearing earlier in NewReplacer's arguments is used.

But I feel like we could go on forever 😄 Maybe it's time to submit a CL? Do you want to do it or should I go ahead?

[pam4]

@rentziass, your wording sounds fine to me. Please go ahead with the CL if you are willing. Thanks!

[gopherbot]

Change https://golang.org/cl/185099 mentions this issue: strings: document that order of pairs matters in NewReplacer