std.regex replaceFirst vs. replaceFirstInto

[Chris via Digitalmars-d]

std.regex.replaceFirst uses

https://github.com/D-Programming-Language/phobos/blob/master/std/regex/package.d#L734

which returns the input, if no match is found. This is "safe", 
because the worst thing that can happen is that you get the input 
back unchanged.

std.regex.replaceFirstInto, on the other hand, uses

https://github.com/D-Programming-Language/phobos/blob/master/std/regex/package.d#L700

which may throw an exception like this:

phobos/std/regex/package.d(993): invalid submatch number 1*

Shouldn't this be reflected in the documentation? At the moment, 
the documentation of replaceFirstInto says:

"A variation on replaceFirst that instead of allocating a new 
string on each call outputs the result piece-wise to the sink."

But it doesn't mention the difference in behavior (i.e. return 
input vs. exception). In other words, with replaceFirstInto, you 
have to make sure that you can indeed replace.

The same probably goes for replaceAll / replaceAllInto.

*Exception stems from
https://github.com/D-Programming-Language/phobos/blob/master/std/regex/package.d#L962