From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#12325: 24.2.50; doc of `replace-match' for STRING case Date: Sat, 1 Sep 2012 12:55:26 -0700 Message-ID: <4D9B083938704AA193485E05A2073C3A@us.oracle.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1346529407 20177 80.91.229.3 (1 Sep 2012 19:56:47 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 1 Sep 2012 19:56:47 +0000 (UTC) To: 12325@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Sep 01 21:56:49 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1T7toE-0000wa-Nn for geb-bug-gnu-emacs@m.gmane.org; Sat, 01 Sep 2012 21:56:46 +0200 Original-Received: from localhost ([::1]:37447 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T7toC-0004Qj-Aw for geb-bug-gnu-emacs@m.gmane.org; Sat, 01 Sep 2012 15:56:44 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:55006) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T7to8-0004Pz-PP for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:56:41 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T7to7-0001p1-Gm for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:56:40 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:51913) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T7to7-0001or-Df for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:56:39 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1T7tpR-0007vH-Qy for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:58:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 01 Sep 2012 19:58:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 12325 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.134652943030392 (code B ref -1); Sat, 01 Sep 2012 19:58:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 1 Sep 2012 19:57:10 +0000 Original-Received: from localhost ([127.0.0.1]:33226 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1T7tob-0007u8-Pb for submit@debbugs.gnu.org; Sat, 01 Sep 2012 15:57:10 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:56672) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1T7toZ-0007u1-Qp for submit@debbugs.gnu.org; Sat, 01 Sep 2012 15:57:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T7tnE-000119-04 for submit@debbugs.gnu.org; Sat, 01 Sep 2012 15:55:45 -0400 Original-Received: from lists.gnu.org ([208.118.235.17]:46901) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T7tnD-000114-TP for submit@debbugs.gnu.org; Sat, 01 Sep 2012 15:55:43 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:53321) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T7tnC-0004DB-Le for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:55:43 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T7tnB-00010V-02 for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:55:42 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]:48074) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T7tnA-00010Q-Pw for bug-gnu-emacs@gnu.org; Sat, 01 Sep 2012 15:55:40 -0400 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by acsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q81JtZl0000417 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 1 Sep 2012 19:55:38 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q81JtY6x005731 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 1 Sep 2012 19:55:35 GMT Original-Received: from abhmt110.oracle.com (abhmt110.oracle.com [141.146.116.62]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q81JtYNB015924 for ; Sat, 1 Sep 2012 14:55:34 -0500 Original-Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 01 Sep 2012 12:55:34 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac2Ie7sBfcuwjLtuQKKxZtjmoaHhkA== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:63654 Archived-At: The doc, both the doc string and the Elisp manual entry, is not sufficiently clear that for the non-nil STRING case `replace-match' does NOT modify STRING but returns a new string. That the function returns a new string is said, but that statement is buried among other statements that give the impression that STRING is modified. Here are such misleading statements: Doc string ---------- "STRING can be a string to modify." No, STRING is never modified. "returns a new string made by copying STRING and replacing the part of STRING that was matched." No, it does NOT replace any "part of STRING". It replaces the part of the *copy* that corresponds to the matched portion of STRING. Elisp manual ------------ "This function replaces the text in the buffer (or in STRING) that was matched by the last search. It replaces that text with REPLACEMENT." No, it never replaces any text in STRING. It does not replace the text in STRING that was matched - that matched text is a part of STRING and stays as it was. It replaces corresponding text in a *copy* of STRING. "`replace-match' does the replacement by constructing and returning a new string." This is not as clear as it should be. "Does the replacement" is unclear. What replacement? A reader will easily assume here that we mean a replacement in STRING, which is wrong. It "does the replacement" IN a copy of string, and then returns the modified copy. For both the doc string and the manual, we should be very clear that unlike the case where STRING is nil, where the original buffer text *is* replaced, when STRING is a string it is left unmodified and the return value is a copy of STRING with the text corresponding to the match in STRING replaced by REPLACEMENT. In the buffer case, `replace-match' modifies the target object (the buffer). In the string case, `replace-match' is a non-destructive operation. The doc does not make this sufficiently clear, seemingly because it tries to treat the two cases together using the same wording, and with the string case almost as an afterthought: "replaces the text in the buffer (or in STRING)". Treat the two cases separately, and make clear that one modifies the target and the other does not. In the STRING case it is really misleading to speak of "replacement", since one naturally assumes that a replacement takes place in STRING. Because of this, the doc needs to take pains to counter this, explicitly emphasizing that in spite of the function name, and just as for the case of other non-destructive functions with names such as `remove', this function does not modify STRING. In GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600) of 2012-08-26 on MARVIN Bzr revision: 109788 dmantipov@yandex.ru-20120827041533-3cy7pdjdqz14o90c Windowing system distributor `Microsoft Corp.', version 5.1.2600 Configured using: `configure --with-gcc (4.6) --no-opt --enable-checking --cflags -ID:/devel/emacs/libs/libXpm-3.5.8/include -ID:/devel/emacs/libs/libXpm-3.5.8/src -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include -ID:/devel/emacs/libs/giflib-4.1.4-1/include -ID:/devel/emacs/libs/jpeg-6b-4/include -ID:/devel/emacs/libs/tiff-3.8.2-1/include -ID:/devel/emacs/libs/gnutls-3.0.9/include -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'