Improve str_replace documentation re: regex (preg_replace)

Problem/Motivation

str_replace regex use case documentation could be improved.

Proposed resolution

If nothing else, another line similar to this one about PHP str_replace (docblock > around line 57)

 * All the rules for
 * @link http://php.net/manual/function.str-replace.php str_replace @endlink
 * apply. This means that you can provide arrays as values.

In other words, something like "When regex is true, all the rules for preg_replace apply? -- i.e. "that means your replace string can include backreferences." -- and maybe an example, but I understand if that would be too many examples (or maybe the existing regex example could be updated to include a backreference).

Remaining tasks

(do, or do not)

I'd be happy to submit a patch if there's support for the idea. Thank you!