mention the issue of fallibility in replacements in the API docs

[obsgolem]

Currently the Replacer trait returns a string. If you have complicated replacement logic, there is a decent chance that you want to be able to return a Result or an Option instead, with short circuiting behavior. The API would basically be to add try variants of replace_all and replacen and a new FallibleReplacer trait with an associated Error type.

[BurntSushi]

I think in cases like this, it would be best to just write your own replacement routine. replace_all is not a particularly complicated routine IMO, and I'd really rather folks do that at this point than bloating the API.

This has been discussed somewhat before in #648, and note that I wrote a fallible replacement routine in 10 not-too-complex lines.

[obsgolem]

All right, I am content with that. I feel it might be worth noting that recommendation in the docs. Something like

If the replace operation might fail, consider using implementing the replacement manually with captures_iter.