bug#20395: 24.3; Documentation for `replace-regexp-in-string'

[Eli Zaretskii <eliz@gnu.org>]

> From: Eli Barzilay <eli@barzilay.org>
> Date: Tue, 21 Apr 2015 05:59:01 -0400
> 
> (In GNU Emacs 24.3.1, but same in git)
> 
> I tried to use `replace-regexp-in-string' like this:
> 
>     (let ((text "foo\nbar\nbaz\n") (r "*"))
>       (replace-regexp-in-string
>        "\n\\(.\\)"
>        (lambda (_) (concat "\n" r (match-string 1 text)))
>        text))
> 
> and it surprised me that this didn't work.  Looking at the docstring,
> I found this
> 
>     When REP is called, the match data are the result of matching
>     REGEXP against a substring of STRING.
> 
> and IMO that "a substring" is very subtle and easy to miss.  I then
> looked at the code, and at least in its current form, I saw that I
> could do this instead:
> 
>     (let ((text "foo\nbar\nbaz\n") (r "*"))
>       (replace-regexp-in-string
>        "\n\\(.\\)"
>        (lambda (s) (concat "\n" r (match-string 1 s)))
>        text))
> 
> So I think that it would be really good if this was made explicit in
> the documentation, better with an example.  Something like
> 
>     When REP is called, the match data are the result of matching
>     REGEXP against only the currently matched substring of STRING.
>     For example, (lambda (s) (concat "<" (match-string 1 s) ">")) as
>     REP is equivalent to "<\\1>".

I tried to clarify this issue in a slightly different way.