From unknown Mon Jun 23 13:07:52 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#12325 <12325@debbugs.gnu.org> To: bug#12325 <12325@debbugs.gnu.org> Subject: Status: 24.2.50; doc of `replace-match' for STRING case Reply-To: bug#12325 <12325@debbugs.gnu.org> Date: Mon, 23 Jun 2025 20:07:52 +0000 retitle 12325 24.2.50; doc of `replace-match' for STRING case reassign 12325 emacs submitter 12325 "Drew Adams" severity 12325 minor thanks From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 01 15:57:10 2012 Received: (at submit) by debbugs.gnu.org; 1 Sep 2012 19:57:10 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.2 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 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 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 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 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 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 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 Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 01 Sep 2012 12:55:34 -0700 From: "Drew Adams" To: Subject: 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> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit 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-Received-From: 208.118.235.17 X-Spam-Score: -6.1 (------) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.1 (------) 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' From debbugs-submit-bounces@debbugs.gnu.org Sat Sep 22 11:28:46 2012 Received: (at 12325-done) by debbugs.gnu.org; 22 Sep 2012 15:28:46 +0000 Received: from localhost ([127.0.0.1]:49269 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TFRdN-0006fQ-Pm for submit@debbugs.gnu.org; Sat, 22 Sep 2012 11:28:45 -0400 Received: from mail-pa0-f44.google.com ([209.85.220.44]:44124) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TFRdL-0006fI-MR for 12325-done@debbugs.gnu.org; Sat, 22 Sep 2012 11:28:44 -0400 Received: by padfb11 with SMTP id fb11so754512pad.3 for <12325-done@debbugs.gnu.org>; Sat, 22 Sep 2012 08:26:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-type; bh=2isTQmlq60I2QOlheuZA7rePoVw/4AgmO9rqijM2Pyg=; b=QNUqgOIxmmbUlHSqQRgjfTauVXWO+EWfS6ynlMSYHU/EM5bRkUSBNF4Sy1nCc3G9GY xNqZM3+3DaLsI6pKEu1kSU/AslwH2zxzwhqS5KX33sJuFN5IEbmi6R5U8W5gO/9wf0Dk fETaew3cJJrl0kOtzCBr5ToUJZznRC1ms/kA5T9FTT9Qtlqg685UfdPKwfpHneEVPpBj ZwvwIAgA+tQqM4ewZNTPO3FHXL5w01GJ6JJLB5f39BgDhjbYX1nIJM0CJu2DDWD8uluD 5sVhB8h7uhjPCP03Q75V8HA/1T7JwQdc+5CFojD2ULCn/h++Mvyl43vlvECOqCE7J4Dj ga/g== Received: by 10.68.241.232 with SMTP id wl8mr23646346pbc.112.1348327619864; Sat, 22 Sep 2012 08:26:59 -0700 (PDT) Received: from ulysses (cm162.gamma80.maxonline.com.sg. [202.156.80.162]) by mx.google.com with ESMTPS id ps2sm6807493pbb.0.2012.09.22.08.26.57 (version=SSLv3 cipher=OTHER); Sat, 22 Sep 2012 08:26:58 -0700 (PDT) From: Chong Yidong To: "Drew Adams" Subject: Re: bug#12325: 24.2.50; doc of `replace-match' for STRING case References: <4D9B083938704AA193485E05A2073C3A@us.oracle.com> Date: Sat, 22 Sep 2012 23:26:55 +0800 In-Reply-To: <4D9B083938704AA193485E05A2073C3A@us.oracle.com> (Drew Adams's message of "Sat, 1 Sep 2012 12:55:26 -0700") Message-ID: <87vcf6dqo0.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.2.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.6 (--) X-Debbugs-Envelope-To: 12325-done Cc: 12325-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) "Drew Adams" writes: > 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. Fixed in trunk. From unknown Mon Jun 23 13:07:52 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 21 Oct 2012 11:24:03 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator