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

1 files changed, 15 insertions, 9 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index a0ae4b165c..4f35dfbe4a 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