From: Dave Mitchell <davem@fdisolutions.com>
Date: Mon, 1 Mar 2004 23:59:21 +0000 (+0000)
Subject: Document the new behaviour of the substr lvalue :
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=91f73676a9125d9b3d3f28a7074c33d41fa4f092;p=p5sagit%2Fp5-mst-13.2.git

Document the new behaviour of the substr lvalue :
Subject: Re: [perl #24346] pulling in stuff from outside the substr lvalue window
Message-ID: <20040301235921.GC6469@fdisolutions.com>

p4raw-id: //depot/perl@22488
---

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index a0ae4b1..4f35dfb 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -5578,15 +5578,21 @@ replacement string as the 4th argument.  This allows you to replace
 parts of the EXPR and return what was there before in one operation,
 just as you can with splice().
 
-If the lvalue returned by substr is used after the EXPR is changed in
-any way, the behaviour may not be as expected and is subject to change.
-This caveat includes code such as C<print(substr($foo,$a,$b)=$bar)> or
-C<(substr($foo,$a,$b)=$bar)=$fud> (where $foo is changed via the
-substring assignment, and then the substr is used again), or where a
-substr() is aliased via a C<foreach> loop or passed as a parameter or
-a reference to it is taken and then the alias, parameter, or deref'd
-reference either is used after the original EXPR has been changed or
-is assigned to and then used a second time.
+Note that the lvalue returned by by the 3-arg version of substr() acts as
+a 'magic bullet'; each time it is assigned to, it remembers which part
+of the original string is being modified; for example:
+
+    $x = '1234';
+    for (substr($x,1,2)) {
+        $_ = 'a';   print $x,"\n";	# prints 1a4
+        $_ = 'xyz'; print $x,"\n";	# prints 1xyz4
+        $x = '56789';
+        $_ = 'pq';  print $x,"\n";	# prints 5pq9
+    }
+
+
+Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
+unspecified.
 
 =item symlink OLDFILE,NEWFILE