bug#58177: Return value of perform-replace and its documentation string

[Ruy Exel]

This bug report was suggested to me by Emacs Stack Exchange user
"db48x" in a reply to my question "How to count number of replacements
made by "query-replace?"
(https://emacs.stackexchange.com/questions/73860/how-to-count-number-of-replacements-made-by-query-replace)
and corroborated by user "dalanicolai".

Primarily this is related to the documentation string of the emacs
function "perform-replace" which says:

"This function returns nil if and only if there were no matches to
make, or the user didn’t cancel the call."

Since the return value IS NIL when the user DID cancel the call, the
documentation string appears to be incorrect.

On the other hand, it seems to me that the actual behavior, namely
returning nil upon cancellation, is not the ideal behavior.

Recall that the return value of perform-replace, when not interrupted
by the user, is a list giving information regarding the replacements
tried, including those actually made.

In case the user decides to reply "yes" to the first few queries, and
then decides to reply with "q", canceling the command, the return
value of nil cannot be used to determine which replacements were made,
which in turn might be of interest in certain circumstances, as in the
one described in my Emacs Stack Exchange question mentioned above.

Thus, I would like to add a feature request to this bug report, namely
that the return value of perform-replace, in case it is canceled by
the user, be changed from nil to some other value reflecting the
replacements considered before the cancel request.

Yours,
Ruy Exel