X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlref.pod;h=2727e95ae91e78060a57daf5ee65203241a9937b;hb=a13595b5281fdbbbab355732a452b568bedb399e;hp=5958a7233c8a2b637da7dc32df2c27408afca1d3;hpb=7c2ea1c74a297a6e4f5e99f73e5cadca30825f36;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlref.pod b/pod/perlref.pod
index 5958a72..2727e95 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -84,7 +84,7 @@ brackets:
 Here we've created a reference to an anonymous array of three elements
 whose final element is itself a reference to another anonymous array of three
 elements.  (The multidimensional syntax described later can be used to
-access this.  For example, after the above, C<$arrayref-E<gt>[2][1]> would have
+access this.  For example, after the above, C<< $arrayref->[2][1] >> would have
 the value "b".)
 
 Taking a reference to an enumerated list is not the same
@@ -357,7 +357,7 @@ syntactic sugar, the examples for method 2 may be written:
 
 The left side of the arrow can be any expression returning a reference,
 including a previous dereference.  Note that C<$array[$x]> is I<not> the
-same thing as C<$array-E<gt>[$x]> here:
+same thing as C<< $array->[$x] >> here:
 
     $array[$x]->{"foo"}->[0] = "January";
 
@@ -365,7 +365,7 @@ This is one of the cases we mentioned earlier in which references could
 spring into existence when in an lvalue context.  Before this
 statement, C<$array[$x]> may have been undefined.  If so, it's
 automatically defined with a hash reference so that we can look up
-C<{"foo"}> in it.  Likewise C<$array[$x]-E<gt>{"foo"}> will automatically get
+C<{"foo"}> in it.  Likewise C<< $array[$x]->{"foo"} >> will automatically get
 defined with an array reference so that we can look up C<[0]> in it.
 This process is called I<autovivification>.
 
@@ -528,7 +528,8 @@ makes it more than a bareword:
     $array{ +shift }
     $array{ shift @_ }
 
-The B<-w> switch will warn you if it interprets a reserved word as a string.
+The C<use warnings> pragma or the B<-w> switch will warn you if it
+interprets a reserved word as a string.
 But it will no longer warn you about using lowercase words, because the
 string is effectively quoted.
 
@@ -546,22 +547,58 @@ For this to work, the array must contain extra information.  The first
 element of the array has to be a hash reference that maps field names
 to array indices.  Here is an example:
 
-   $struct = [{foo => 1, bar => 2}, "FOO", "BAR"];
+    $struct = [{foo => 1, bar => 2}, "FOO", "BAR"];
 
-   $struct->{foo};  # same as $struct->[1], i.e. "FOO"
-   $struct->{bar};  # same as $struct->[2], i.e. "BAR"
+    $struct->{foo};  # same as $struct->[1], i.e. "FOO"
+    $struct->{bar};  # same as $struct->[2], i.e. "BAR"
 
-   keys %$struct;   # will return ("foo", "bar") in some order
-   values %$struct; # will return ("FOO", "BAR") in same some order
+    keys %$struct;   # will return ("foo", "bar") in some order
+    values %$struct; # will return ("FOO", "BAR") in same some order
 
-   while (my($k,$v) = each %$struct) {
+    while (my($k,$v) = each %$struct) {
        print "$k => $v\n";
-   }
+    }
+
+Perl will raise an exception if you try to access nonexistent fields.
+To avoid inconsistencies, always use the fields::phash() function
+provided by the C<fields> pragma.
+
+    use fields;
+    $pseudohash = fields::phash(foo => "FOO", bar => "BAR");
+
+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 existence of a key in a
+pseudo-hash.  The first is to use exists().  This checks to see if the
+given field has ever been set.  It acts this way to match the behavior
+of a regular hash.  For instance:
+
+    use fields;
+    $phash = fields::phash([qw(foo bar pants)], ['FOO']);
+    $phash->{pants} = undef;
+
+    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.
+
+    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.
 
-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
-do the translation from field names to array indices at compile time for
-typed object references.  See L<fields>.
+    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