support delete() and exists() on array, tied array, and pseudo-hash

elements or slices

p4raw-id: //depot/perl@4796

4 files changed, 95 insertions, 37 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 47f7c26651..b205c7480c 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -425,6 +425,22 @@ This is rather similar to how the arrow may be omitted from
 C<$foo[10]->{'foo'}>.  Note however, that the arrow is still
 required for C<foo(10)->('bar')>.
 
+=head2 exists() and delete() are supported on array elements
+
+The exists() and delete() builtins now work on simple arrays as well.
+The behavior is similar to that on hash elements.
+
+exists() can be used to check whether an array element exists without
+autovivifying it.  If the array is tied, the EXISTS() method in the
+corresponding tied package will be invoked.
+
+delete() may now be used to remove an element from the array and return
+it.  If the element happens to be the one at the end, the size of the
+array also shrinks by one.  If the array is tied, the DELETE() method
+in the corresponding tied package will be invoked.
+
+See L<perlfunc/exists> and L<perlfunc/delete> for examples.
+
 =head2 syswrite() ease-of-use
 
 The length argument of C<syswrite()> has become optional.
@@ -812,6 +828,10 @@ been corrected.
 When applied to a pseudo-hash element, exists() now reports whether
 the specified value exists, not merely if the key is valid.
 
+delete() now works on pseudo-hashes.  When given a pseudo-hash element
+or slice it deletes the values corresponding to the keys (but not the keys
+themselves).  See L<perlref/"Pseudo-hashes: Using an array as a hash">.
+
 =head2 C<goto &sub> and AUTOLOAD
 
 The C<goto &sub> construct works correctly when C<&sub> happens
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 8928df128c..161ebaaf28 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -925,35 +925,52 @@ See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR
 
-Deletes the specified key(s) and their associated values from a hash.
-For each key, returns the deleted value associated with that key, or
-the undefined value if there was no such key.  Deleting from C<$ENV{}>
-modifies the environment.  Deleting from a hash tied to a DBM file
-deletes the entry from the DBM file.  (But deleting from a C<tie>d hash
-doesn't necessarily return anything.)
+Given an expression that specifies a hash element, array element, hash slice,
+or array slice, deletes the specified element(s) from the hash or array.
+If the array elements happen to be at the end of the array, the size
+of the array will shrink by that number of elements.
 
-The following deletes all the values of a hash:
+Returns each element so deleted or the undefined value if there was no such
+element.  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.
+
+The following (inefficiently) deletes all the values of %HASH and @ARRAY:
 
     foreach $key (keys %HASH) {
 	delete $HASH{$key};
     }
 
-And so does this:
+    foreach $index (0 .. $#ARRAY) {
+	delete $ARRAY[$index];
+    }
+
+And so do these:
 
-    delete @HASH{keys %HASH}
+    delete @HASH{keys %HASH};
+
+    delete @ARRAY{0 .. $#ARRAY};
 
 But both of these are slower than just assigning the empty list
-or undefining it:
+or undefining %HASH or @ARRAY:
+
+    %HASH = ();		# completely empty %HASH
+    undef %HASH;	# forget %HASH ever existed
 
-    %hash = ();		# completely empty %hash
-    undef %hash;	# forget %hash every existed
+    @ARRAY = ();	# completely empty @ARRAY
+    undef @ARRAY;	# forget @ARRAY ever existed
 
 Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash element lookup or hash slice:
+operation is a hash element, array element,  hash slice, or array slice
+lookup:
 
     delete $ref->[$x][$y]{$key};
     delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
 
+    delete $ref->[$x][$y][$index];
+    delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
+
+
 =item die LIST
 
 Outside an C<eval>, prints the value of LIST to C<STDERR> and
@@ -1386,27 +1403,36 @@ any C<DESTROY> methods in your objects.
 
 =item exists EXPR
 
-Returns true if the specified hash key exists in its hash, even
-if the corresponding value is undefined.
+Given an expression that specifies a hash element or array element,
+returns true if the specified element exists in the hash or array,
+even if the corresponding value is undefined.  The element is not
+autovivified if it doesn't exist.
 
-    print "Exists\n" 	if exists $array{$key};
-    print "Defined\n" 	if defined $array{$key};
-    print "True\n"      if $array{$key};
+    print "Exists\n" 	if exists $hash{$key};
+    print "Defined\n" 	if defined $hash{$key};
+    print "True\n"      if $hash{$key};
+
+    print "Exists\n" 	if exists $array[$index];
+    print "Defined\n" 	if defined $array[$index];
+    print "True\n"      if $array[$index];
 
 A hash element can be true only if it's defined, and defined if
 it exists, but the reverse doesn't necessarily hold true.
 
 Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash key lookup:
+operation is a hash or array key lookup:
 
     if (exists $ref->{A}->{B}->{$key}) 	{ }
     if (exists $hash{A}{B}{$key}) 	{ }
 
-Although the last element will not spring into existence just because
-its existence was tested, intervening ones will.  Thus C<$ref-E<gt>{"A"}>
-and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring into existence due to the
-existence test for a $key element.  This happens anywhere the arrow
-operator is used, including even 
+    if (exists $ref->{A}->{B}->[$ix]) 	{ }
+    if (exists $hash{A}{B}[$ix]) 	{ }
+
+Although the deepest nested array or hash will not spring into existence
+just because its existence was tested, any intervening ones will.
+Thus C<$ref-E<gt>{"A"}> and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring
+into existence due to the existence test for the $key element above.
+This happens anywhere the arrow operator is used, including even:
 
     undef $ref;
     if (exists $ref->{"Some key"})	{ }
diff --git a/pod/perlref.pod b/pod/perlref.pod
index 12bc581a6d..f738399c9a 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -558,29 +558,39 @@ to array indices.  Here is an example:
        print "$k => $v\n";
    }
 
-Perl will raise an exception if you try to delete keys from a pseudo-hash
-or try to access nonexistent fields.  For better performance, Perl can also
+Perl will raise an exception if you try to access nonexistent fields.
+For better performance, Perl can also
 do the translation from field names to array indices at compile time for
 typed object references.  See L<fields>.
 
-There are two ways to check for the existance of a key in a
+There are two ways to check for the existence of a key in a
 pseudo-hash.  The first is to use exists().  This checks to see if the
-given field has been used yet.  It acts this way to match the behavior
+given field has ever been set.  It acts this way to match the behavior
 of a regular hash.  For instance:
 
 	$phash = [{foo =>1, bar => 2, pants => 3}, 'FOO'];
 	$phash->{pants} = undef;
 
-	exists $phash->{foo};    # true, 'foo' was set in the declaration
-	exists $phash->{bar};    # false, 'bar' has not been used.
-	exists $phash->{pants};  # true, your 'pants' have been touched
+	print exists $phash->{foo};    # true, 'foo' was set in the declaration
+	print exists $phash->{bar};    # false, 'bar' has not been used.
+	print exists $phash->{pants};  # true, your 'pants' have been touched
 
 The second is to use exists() on the hash reference sitting in the
 first array element.  This checks to see if the given key is a valid
 field in the pseudo-hash.
 
-	exists $phash->[0]{bar};	# true, 'bar' is a valid field
-	exists $phash->[0]{shoes};	# false, 'shoes' can't be used
+	print exists $phash->[0]{bar};	# true, 'bar' is a valid field
+	print exists $phash->[0]{shoes};# false, 'shoes' can't be used
+
+delete() on a pseudo-hash element only deletes the value corresponding
+to the key, not the key itself.  To delete the key, you'll have to
+explicitly delete it from the first hash element.
+
+	print delete $phash->{foo};     # prints $phash->[1], "FOO"
+	print exists $phash->{foo};     # false
+	print exists $phash->[0]{foo};  # true, key still exists
+	print delete $phash->[0]{foo};  # now key is gone
+	print $phash->{foo};            # runtime exception
 
 =head2 Function Templates
 
diff --git a/pod/perltie.pod b/pod/perltie.pod
index 5611174669..58e9c4375b 100644
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -185,10 +185,12 @@ methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps DESTROY.
 FETCHSIZE and STORESIZE are used to provide C<$#array> and
 equivalent C<scalar(@array)> access.
     
-The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE are required if the perl
-operator with the corresponding (but lowercase) name is to operate on the
-tied array. The B<Tie::Array> class can be used as a base class to implement
-these in terms of the basic five methods above.  
+The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are
+required if the perl operator with the corresponding (but lowercase) name
+is to operate on the tied array. The B<Tie::Array> class can be used as a
+base class to implement the first five of these in terms of the basic
+methods above.  The default implementations of DELETE and EXISTS in
+B<Tie::Array> simply C<croak>.
 
 In addition EXTEND will be called when perl would have pre-extended 
 allocation in a real array.