From d361fafa2ec7914fdb219a034554936dd4d6cdc7 Mon Sep 17 00:00:00 2001
From: Vincent Pit <perl@profvince.com>
Date: Mon, 27 Jul 2009 16:13:33 +0200
Subject: [PATCH] Document "delete local" in perlsub

---
 pod/perlfunc.pod |  8 ++++++++
 pod/perlsub.pod  | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 23e5535..3a345aa 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1234,6 +1234,10 @@ lookup:
     delete $ref->[$x][$y][$index];
     delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
 
+The C<delete local EXPR> construct can also be used to localize the deletion
+of array/hash elements to the current block.
+See L<perlsub/"Localized deletion of elements of composite types">.
+
 =item die LIST
 X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
 
@@ -2736,6 +2740,10 @@ block, file, or eval.  If more than one value is listed, the list must
 be placed in parentheses.  See L<perlsub/"Temporary Values via local()">
 for details, including issues with tied arrays and hashes.
 
+The C<delete local EXPR> construct can also be used to localize the deletion
+of array/hash elements to the current block.
+See L<perlsub/"Localized deletion of elements of composite types">.
+
 =item localtime EXPR
 X<localtime> X<ctime>
 
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 74d0b1a..325c823 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -535,6 +535,7 @@ Synopsis:
     local @oof = @bar;		# make @oof dynamic, and init it
 
     local $hash{key} = "val";	# sets a local value for this hash entry
+    delete local $hash{key};    # delete this entry for the current block
     local ($cond ? $v1 : $v2);	# several types of lvalues support
 				# localization
 
@@ -692,6 +693,55 @@ Perl will print
 The behavior of local() on non-existent members of composite
 types is subject to change in future.
 
+=head3 Localized deletion of elements of composite types
+X<delete> X<local, composite type element> X<local, array element> X<local, hash element>
+
+You can use the C<delete local $array[$idx]> and C<delete local $hash{key}>
+constructs to delete a composite type entry for the current block and restore
+it when it ends. They return the array/hash value before the localization,
+which means that they are respectively equivalent to
+
+    do {
+        my $val = $array[$idx];
+        local  $array[$idx];
+        delete $array[$idx];
+        $val
+    }
+
+and
+
+    do {
+        my $val = $hash{key};
+        local  $hash{key};
+        delete $hash{key};
+        $val
+    }
+
+except that for those the C<local> is scoped to the C<do> block. Slices are
+also accepted.
+
+    my %hash = (
+     a => [ 7, 8, 9 ],
+     b => 1,
+    )
+
+    {
+     my $a = delete local $hash{a};
+     # $a is [ 7, 8, 9 ]
+     # %hash is (b => 1)
+
+     {
+      my @nums = delete local @$a[0, 2]
+      # @nums is (7, 9)
+      # $a is [ undef, 8 ]
+
+      $a[0] = 999; # will be erased when the scope ends
+     }
+     # $a is back to [ 7, 8, 9 ]
+
+    }
+    # %hash is back to its original state
+
 =head2 Lvalue subroutines
 X<lvalue> X<subroutine, lvalue>
 
-- 
2.7.4