Allow push/pop/keys/etc to act on references

All built-in functions that operate directly on array or hash
containers now also accept hard references to arrays or hashes:

  |----------------------------+---------------------------|
  | Traditional syntax         | Terse syntax              |
  |----------------------------+---------------------------|
  | push @$arrayref, @stuff    | push $arrayref, @stuff    |
  | unshift @$arrayref, @stuff | unshift $arrayref, @stuff |
  | pop @$arrayref             | pop $arrayref             |
  | shift @$arrayref           | shift $arrayref           |
  | splice @$arrayref, 0, 2    | splice $arrayref, 0, 2    |
  | keys %$hashref             | keys $hashref             |
  | keys @$arrayref            | keys $arrayref            |
  | values %$hashref           | values $hashref           |
  | values @$arrayref          | values $arrayref          |
  | ($k,$v) = each %$hashref   | ($k,$v) = each $hashref   |
  | ($k,$v) = each @$arrayref  | ($k,$v) = each $arrayref  |
  |----------------------------+---------------------------|

This allows these built-in functions to act on long dereferencing
chains or on the return value of subroutines without needing to wrap
them in C<@{}> or C<%{}>:

  push @{$obj->tags}, $new_tag;  # old way
  push $obj->tags,    $new_tag;  # new way

  for ( keys %{$hoh->{genres}{artists}} ) {...} # old way
  for ( keys $hoh->{genres}{artists}    ) {...} # new way

For C<push>, C<unshift> and C<splice>, the reference will auto-vivify
if it is not defined, just as if it were wrapped with C<@{}>.

Calling C<keys> or C<values> directly on a reference gives a
substantial performance improvement over explicit dereferencing.

For C<keys>, C<values>, C<each>, when overloaded dereferencing is
present, the overloaded dereference is used instead of dereferencing
the underlying reftype.  Warnings are issued about assumptions made in
the following three ambiguous cases:

  (a) If both %{} and @{} overloading exists, %{} is used
  (b) If %{} overloading exists on a blessed arrayref, %{} is used
  (c) If @{} overloading exists on a blessed hashref, @{} is used

1 files changed, 5 insertions, 5 deletions

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index c16db28937..cfa4ad4183 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -1053,7 +1053,7 @@ X<prototype> X<subroutine, prototype>
 Perl supports a very limited kind of compile-time argument checking
 using function prototyping.  If you declare
 
-    sub mypush (\@@)
+    sub mypush (+@)
 
 then C<mypush()> takes arguments exactly like C<push()> does.  The
 function declaration must be visible at compile time.  The prototype
@@ -1083,9 +1083,9 @@ corresponding built-in.
     sub mysyswrite ($$$;$)   mysyswrite $buf, 0, length($buf) - $off, $off
     sub myreverse (@)	     myreverse $a, $b, $c
     sub myjoin ($@)	     myjoin ":", $a, $b, $c
-    sub mypop (\@)	     mypop @array
-    sub mysplice (\@$$@)     mysplice @array, 0, 2, @pushme
-    sub mykeys (\%)	     mykeys %{$hashref}
+    sub mypop (+)	     mypop @array
+    sub mysplice (+$$@)	     mysplice @array, 0, 2, @pushme
+    sub mykeys (+)	     mykeys %{$hashref}
     sub myopen (*;$)	     myopen HANDLE, $name
     sub mypipe (**)	     mypipe READHANDLE, WRITEHANDLE
     sub mygrep (&@)	     mygrep { /foo/ } $a, $b, $c
@@ -1141,7 +1141,7 @@ C<\[@%]> when given a literal array or hash variable, but will otherwise
 force scalar context on the argument.  This is useful for functions which
 should accept either a literal array or an array reference as the argument:
 
-    sub smartpush (+@) {
+    sub mypush (+@) {
         my $aref = shift;
         die "Not an array or arrayref" unless ref $aref eq 'ARRAY';
         push @$aref, @_;