[DOCPATCH] perlfunc delete

Message-Id: <p05111b07bc0269065a99@[192.168.56.3]>

p4raw-id: //depot/perl@21912

1 files changed, 12 insertions, 2 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 7c69ff6028..8b13ebd9c5 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1033,8 +1033,18 @@ In the case of an array, if the array elements happen to be at the end,
 the size of the array will shrink to the highest element that tests
 true for exists() (or 0 if no such element exists).
 
-Returns each element so deleted or the undefined value if there was no such
-element.  Deleting from C<$ENV{}> modifies the environment.  Deleting from
+Returns a list with the same number of elements as the number of elements
+for which deletion was attempted.  Each element of that list consists of
+either the value of the element deleted, or the undefined value.  In scalar
+context, this means that you get the value of the last element deleted (or
+the undefined value if that element did not exist).
+
+    %hash = (foo => 11, bar => 22, baz => 33);
+    $scalar = delete $hash{foo};             # $scalar is 11
+    $scalar = delete @hash{qw(foo bar)};     # $scalar is 22
+    @array  = delete @hash{qw(foo bar baz)}; # @array  is (undef,undef,33)
+
+Deleting from C<%ENV> modifies the environment.  Deleting from
 a hash tied to a DBM file deletes the entry from the DBM file.  Deleting
 from a C<tie>d hash or array may not necessarily return anything.