[win32] integrate mainline

[p5sagit/p5-mst-13.2.git] / pod / perlsub.pod

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index d08426a..c66bcb6 100644 (file)
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -504,6 +504,45 @@ like this:
     }
     [..normal %ENV behavior here..]
 
+It's also worth taking a moment to explain what happens when you
+localize a member of a composite type (i.e. an array or hash element).
+In this case, the element is localized I<by name>. This means that
+when the scope of the C<local()> ends, the saved value will be
+restored to the hash element whose key was named in the C<local()>, or
+the array element whose index was named in the C<local()>.  If that
+element was deleted while the C<local()> was in effect (e.g. by a
+C<delete()> from a hash or a C<shift()> of an array), it will spring
+back into existence, possibly extending an array and filling in the
+skipped elements with C<undef>.  For instance, if you say
+
+    %hash = ( 'This' => 'is', 'a' => 'test' );
+    @ary  = ( 0..5 );
+    {
+         local($ary[5]) = 6;
+         local($hash{'a'}) = 'drill';
+         while (my $e = pop(@ary)) {
+             print "$e . . .\n";
+             last unless $e > 3;
+         }
+         if (@ary) {
+             $hash{'only a'} = 'test';
+             delete $hash{'a'};
+         }
+    }
+    print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
+    print "The array has ",scalar(@ary)," elements: ",
+          join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
+
+Perl will print
+
+    6 . . .
+    4 . . .
+    3 . . .
+    This is a test only a test.
+    The array has 6 elements: 0, 1, 2, undef, undef, 5
+
+In short, be careful when manipulating the containers for composite types
+whose elements have been localized.
 
 =head2 Passing Symbol Table Entries (typeglobs)
 
@@ -872,6 +911,12 @@ via the import syntax, and these names may then override the builtin ones:
     chdir $somewhere;
     sub chdir { ... }
 
+To unambiguously refer to the builtin form, one may precede the
+builtin name with the special package qualifier C<CORE::>.  For example,
+saying C<CORE::open()> will always refer to the builtin C<open()>, even
+if the current package has imported some other subroutine called
+C<&open()> from elsewhere.
+
 Library modules should not in general export builtin names like "open"
 or "chdir" as part of their default @EXPORT list, because these may
 sneak into someone else's namespace and change the semantics unexpectedly.
@@ -887,6 +932,10 @@ and it would import the open override, but if they said
 
 they would get the default imports without the overrides.
 
+Note that such overriding is restricted to the package that requests
+the import.  Some means of "globally" overriding builtins may become
+available in future.
+
 =head2 Autoloading
 
 If you call a subroutine that is undefined, you would ordinarily get an