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

[Eli Barzilay <eli@barzilay.org>]

(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>".

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!