DOC: replace() method documentation is not clear for confliciting/overlapping dict-based substitutions

[candalfigomoro]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

Example: https://pandas.pydata.org/docs/reference/api/pandas.Series.replace.html

Documentation problem

The behaviour of the replace() method is not clear when there are dictionaries with conflicting substitutions. E.g. suppose that I pass this dictionary as "to_replace" parameter:

d = {
    "word1": "replacement1",
    "word1 word2": "replacement2",
}

and I have a cell with this text: word0 word1 word2 word3

What is the result after calling the replace method()?

word0 replacement1 word2 word3 ???
or
word0 replacement2 word3 ???

How is the priority of confliciting/overlapping dict-based substitutions managed? This is not clearly explained.

Suggested fix for documentation

The documentation should clearly explain the behaviour of the replace() method when there are dictionaries with conflicting/overlapping substitutions.

[zeromh]

There's also no reason for the Series replace documentation to reference Dataframes, as in "For a DataFrame a dict can specify that different values should be replaced in different columns."