RE: [PATCH] Warning on pararameterless 'use IO' and doc update

[perl5.git] / pod / perltie.pod

diff --git a/pod/perltie.pod b/pod/perltie.pod
index 8b3f679..72288a0 100644 (file)
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -161,7 +161,7 @@ argument--the new value the user is trying to assign.
 
 This method will be triggered when the C<untie> occurs. This can be useful
 if the class needs to know when no further calls will be made. (Except DESTROY
-of course.) See below for more details.
+of course.) See L<The C<untie> Gotcha> below for more details.
 
 =item DESTROY this
 
@@ -258,7 +258,9 @@ index whose value we're trying to fetch.
 
 If a negative array index is used to read from an array, the index
 will be translated to a positive one internally by calling FETCHSIZE
-before being passed to FETCH.
+before being passed to FETCH.  You may disable this feature by
+assigning a true value to the variable C<$NEGATIVE_INDICES> in the
+tied array class.
 
 As you may have noticed, the name of the FETCH method (et al.) is the same
 for all accesses, even though the constructors differ in names (TIESCALAR
@@ -311,15 +313,19 @@ deleted.
 In our example, 'undef' is really an element containing
 C<$self-E<gt>{ELEMSIZE}> number of spaces.  Observe:
 
-sub STORESIZE {
-  my $self  = shift;
-  my $count = shift;
-  if ( $count > $self->FETCHSIZE() ) {
-    $self->STORE( $_, '' ) foreach $count - $self->FETCHSIZE() + 1 .. $count;
-  } elsif ( $count < $self->FETCHSIZE() ) {
-    $self->POP() foreach 0 .. $self->FETCHSIZE() - $count + 1;
-  }
-}
+    sub STORESIZE {
+      my $self  = shift;
+      my $count = shift;
+      if ( $count > $self->FETCHSIZE() ) {
+        foreach ( $count - $self->FETCHSIZE() .. $count ) {
+          $self->STORE( $_, '' );
+        }
+      } elsif ( $count < $self->FETCHSIZE() ) {
+        foreach ( 0 .. $self->FETCHSIZE() - $count - 2 ) {
+          $self->POP();
+        }
+      }
+    }
 
 =item EXTEND this, count
 
@@ -346,7 +352,9 @@ C<$self-E<gt>{ELEMSIZE}> spaces only, it does not exist:
     sub EXISTS {
       my $self  = shift;
       my $index = shift;
-      return $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE} ? 0 : 1;
+      return 0 if ! defined $self->{ARRAY}->[$index] ||
+                  $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE};
+      return 1;
     }
 
 =item DELETE this, key
@@ -446,7 +454,7 @@ In our example, we'll use a little shortcut if there is a I<LIST>:
 
 =item UNTIE this
 
-Will be called when C<untie> happens. (See below.)
+Will be called when C<untie> happens. (See L<The C<untie> Gotcha> below.)
 
 =item DESTROY this
 
@@ -457,17 +465,6 @@ just leave it out.
 
 =back
 
-The code we presented at the top of the tied array class accesses many
-elements of the array, far more than we've set the bounds to.  Therefore,
-it will blow up once they try to access beyond the 2nd element of @ary, as
-the following output demonstrates:
-
-    setting index 0: value of elt 0 now 0
-    setting index 1: value of elt 1 now 10
-    setting index 2: value of elt 2 now 20
-    setting index 3: Array OOB: 3 > 2 at Bounded_Array.pm line 39
-            Bounded_Array::FETCH called at testba line 12
-
 =head2 Tying Hashes
 
 Hashes were the first Perl data type to be tied (see dbmopen()).  A class
@@ -480,7 +477,7 @@ the keys.  UNTIE is called when C<untie> happens, and DESTROY is called when
 the tied variable is garbage collected.
 
 If this seems like a lot, then feel free to inherit from merely the
-standard Tie::Hash module for most of your methods, redefining only the
+standard Tie::StdHash module for most of your methods, redefining only the
 interesting ones.  See L<Tie::Hash> for details.
 
 Remember that Perl distinguishes between a key not existing in the hash,
@@ -761,7 +758,7 @@ thing, but we'll have to go through the LIST field indirectly.
 
 =item UNTIE this
 
-This is called when C<untie> occurs.
+This is called when C<untie> occurs.  See L<The C<untie> Gotcha> below.
 
 =item DESTROY this
 
@@ -855,7 +852,7 @@ or C<sysread> functions.
 
     sub READ {
        my $self = shift;
-       my $$bufref = \$_[0];
+       my $bufref = \$_[0];
        my(undef,$len,$offset) = @_;
        print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
        # add to $$bufref, set $len to number of characters read
@@ -885,7 +882,8 @@ function.
 =item UNTIE this
 
 As with the other types of ties, this method will be called when C<untie> happens.
-It may be appropriate to "auto CLOSE" when this occurs.
+It may be appropriate to "auto CLOSE" when this occurs.  See
+L<The C<untie> Gotcha> below.
 
 =item DESTROY this
 
@@ -908,7 +906,7 @@ Here's how to use our little example:
 =head2 UNTIE this
 
 You can define for all tie types an UNTIE method that will be called
-at untie().
+at untie().  See L<The C<untie> Gotcha> below.
 
 =head2 The C<untie> Gotcha
 
@@ -1086,4 +1084,4 @@ TIEHANDLE by Sven Verdoolaege <F<skimo@dns.ufsia.ac.be>> and Doug MacEachern <F<
 
 UNTIE by Nick Ing-Simmons <F<nick@ing-simmons.net>>
 
-Tying Arrays by Casey Tweten <F<crt@kiski.net>>
+Tying Arrays by Casey West <F<casey@geeknest.com>>