bug#45516: 26.3; (elisp) `Modifying Strings': Mention `replace-regexp-in-string'

[Drew Adams <drew.adams@oracle.com>]

> > Subject line says it all.  This is an important function for modifying
> > strings.  Please consider mentioning it, with a cross-reference.
> 
> That node is about destructively modifying strings.
> replace-regexp-in-string doesn't modify anything -- it returns a new
> string.
> 
> But it's odd that there's no mention of replace-regexp-in-string (and
> string-replace) in the Strings section, so I've now added a reference
> from the Creating Strings node.

Yes, you're right that the functions described
there are about destructively modifying.  And
thanks for making some changes for this bug.

But nothing is said in that node about the
kind of modification ("destructive") that's
involved.  A user can want to either modify
in place or return a new string that's the
same as some other string but with some
changes.  In some cases a user doesn't care
which is done.

I think there's room for doc improvement, for
helping users finding functions that "modify"
in either sense, and for making clear just
which kind of "modifying" is meant for each case.

You have a string "abcdefbca", and you want a
string that is the same, but with "bc" replaced
by "xy".  What do you ask for in the Elisp
manual, to find the info you need?