From 3eb35b099f783db0ec40f0ca9f20fd1666c54cdb Mon Sep 17 00:00:00 2001
From: Yves Orton <demerphq@gmail.com>
Date: Thu, 30 Jan 2020 09:36:37 +0100
Subject: [PATCH] perltie.pod: rework example code so EXTEND is a no-op
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Most tied array implementations can and should NO-OP the EXTEND
method, and the sample code should not conflate EXTEND with STORESIZE.

EXTEND is actually less usefully used by the core than it could be
as AvMAX() does not have an equivalent tied method. So we cannot
check if we need to extend for a tied array.

This is related to [rt.cpan.org #39196] / Issue #17496.

Signed-off-by: Petr Písař <ppisar@redhat.com>
---
 pod/perltie.pod | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/pod/perltie.pod b/pod/perltie.pod
index 2d433e8204..1bb220691b 100644
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -301,7 +301,7 @@ spaces so we have a little more work to do here:
      croak "length of $value is greater than $self->{ELEMSIZE}";
    }
    # fill in the blanks
-   $self->EXTEND( $index ) if $index > $self->FETCHSIZE();
+   $self->STORESIZE( $index ) if $index > $self->FETCHSIZE();
    # right justify to keep element size for smaller elements
    $self->{ARRAY}->[$index] = sprintf "%$self->{ELEMSIZE}s", $value;
  }
@@ -351,16 +351,24 @@ X<EXTEND>
 Informative call that array is likely to grow to have I<count> entries.
 Can be used to optimize allocation. This method need do nothing.
 
-In our example, we want to make sure there are no blank (C<undef>)
-entries, so C<EXTEND> will make use of C<STORESIZE> to fill elements
-as needed:
+In our example there is no reason to implement this method, so we leave
+it as a no-op. This method is only relevant to tied array implementations
+where there is the possibility of having the allocated size of the array
+be larger than is visible to a perl programmer inspecting the size of the
+array. Many tied array implementations will have no reason to implement it.
 
     sub EXTEND {   
       my $self  = shift;
       my $count = shift;
-      $self->STORESIZE( $count );
+      # nothing to see here, move along.
     }
 
+B<NOTE:> It is generally an error to make this equivalent to STORESIZE.
+Perl may from time to time call EXTEND without wanting to actually change
+the array size directly. Any tied array should function correctly if this
+method is a no-op, even if perhaps they might not be as efficient as they
+would if this method was implemented.
+
 =item EXISTS this, key
 X<EXISTS>
 
-- 
2.21.1