This is working as intended: replacements are being performed in order on the string linearly, without attempting to replace any text that was replaced.

The docs should be updated to make this more clear.

Makes sense. It didn't occur to me to read it the other way.

Change https://golang.org/cl/109375 mentions this issue: strings: clarify Replacer's replacement order

meaning that substrings are replaced in the order they appear in the target string, and not that the old->new replacements are applied in the order they're passed to NewReplacer.

If more than one pattern matches at the same target string position (a pattern is prefix of another), the one that is applied does depend on the order they're passed to NewReplacer.
But I don't know if it can be conveyed without making the doc too complex.

I agree it is hard to be exhaustive without unnecessarily complicating the doc. The proposed change lgtm

@nicksnyder I'm not sure what I would have done myself, I think it's a pity though.

If I want to replace "var1" -> "var2" and "var" -> "var1" but the order of these two replacements is undocumented, I have no choice but roll up my own implementation to be sure that the order will always be predictable.

Unless the caller knows in advance that no pattern is prefix of another, I think he would generally prefer a predictable behavior (first pattern first? longest pattern first?).

Of course it is also true that if we expose too much details, the docs become less effective for the most common use cases, less clear, and easier to misinterpret.

@pam4

Unless the caller knows in advance that no pattern is prefix of another, I think he would generally prefer a predictable behavior

I'm not sure what about the current behaviour you find "unpredictable". The patterns are replaced in the order they appear in the string, from left to right. If two (old->new) couples has the same "old", the first couple (in the order they're passed as arguments) is used. I believe this constitutes "predictable" behaviour.

Are you suggesting to change something in the implementation? Or to change the documentation? How would you change it? Are you asking to explicitly document the Replacer's behaviour in the "old->new1", "old->new2" case? I think that's a reasonable request.

Are you asking to explicitly document the Replacer's behaviour in the "old->new1", "old->new2" case? I think that's a reasonable request.

Yes, I wondered this myself and had to experiment to find the answer. I found it hard to come up with a pithy doc for it though.

@ALTree thanks for the reply.

Are you suggesting to change something in the implementation?

No.

Are you asking to explicitly document the Replacer's behaviour in the "old->new1", "old->new2" case?

More generally, to explicitly document the behavior of A->B, C->D when C is a prefix of A (or vice versa).

strings.NewReplacer("X1", "X2", "X", "X1").Replace("X1") // "X2"
strings.NewReplacer("X", "X1", "X1", "X2").Replace("X1") // "X11"

If I had some good wording to suggest, I would have done so.

I'm not sure what about the current behaviour you find "unpredictable".

Bad choice of word, it probably is predictable, just not explicitly documented. In your own code, would you rely on it, in cases similar to the example above?

More generally, to explicitly document the behavior of A->B, C->D when C is a prefix of A (or vice versa).

This is already documented, it's the "without overlapping matches" part. "without overlapping matches" means that once we are done with the A->B replacement, we leave that part of the string and move on towards the right.

In your own code, would you rely on it, in cases similar to the example above?

Yes, because it's the documented behaviour.

@ALTree

This is already documented, it's the "without overlapping matches" part. "without overlapping matches" means that once we are done with the A->B replacement, we leave that part of the string and move on towards the right.

Incidentally I made an example with possible overlapping matches, but I wasn't referring to them.
I'm talking about which one of the two pair is used when they both match at the same starting position. The "overlapping" rule doesn't answer that.

Here is another example:

// first pair is used
strings.NewReplacer("ant", "bug", "antique", "old").Replace("antique") // "bugique"
// pairs swapped, again first pair is used
strings.NewReplacer("antique", "old", "ant", "bug").Replace("antique") // "old"

As you said, the first pair is used.
But such rule must cover, not only the case of two pair with the same "old" part, but also the case of an "old" part that is prefix of another "old" part (regardless of the "new" parts).
Otherwise, any of the two examples above could return either "bugique" or "old".

Ah, I see. Thanks for explaining. So it's not just a matter of clarifying what happens with couples having the same exact "old". We should probably also explain that the first couple is given higher priority when there are couples with overlapping "old"s. I'm not even sure this behaviour is actually mandated by the API, or if it's just an artefact of the current implementation.

Yes, that's what I meant.

I'm not even sure this behaviour is actually mandated by the API, or if it's just an artefact of the current implementation.

Well, obviously it was never documented, but looking at the code I presume it was intentional: the generic algorithm uses a lookup trie for prioritized key/value pairs, and keys are added with decreasing priority, here (len(oldnew)-i is the priority).
(Other algorithms are only used in case of single pair or single byte patterns).

And I can think of situations where you need to rely on this priority, that's why I said it's a pity.