From: Shlomi Fish <shlomif@iglu.org.il>
Date: Tue, 18 May 2010 14:42:52 +0000 (+0300)
Subject: Clarify the av_fetch() documentation.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1a32886282d60539000205670909069b85d9eedd;p=p5sagit%2Fp5-mst-13.2.git

Clarify the av_fetch() documentation.

Thanks to LeoNerd and Zefram on #p5p on IRC for some insights and
suggesting versions for the modified text. I ended up using Zefram's
version.

Signed-off-by: David Golden <dagolden@cpan.org>
---

diff --git a/av.c b/av.c
index 33d5d7b..06dc606 100644
--- a/av.c
+++ b/av.c
@@ -191,12 +191,14 @@ Perl_av_extend(pTHX_ AV *av, I32 key)
 =for apidoc av_fetch
 
 Returns the SV at the specified index in the array.  The C<key> is the
-index.  If C<lval> is set then the fetch will be part of a store.  Check
-that the return value is non-null before dereferencing it to a C<SV*>.
+index.  If lval is true, you are guaranteed to get a real SV back (in case
+it wasn't real before), which you can then modify.  Check that the return
+value is non-null before dereferencing it to a C<SV*>.
 
 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
 more information on how to use this function on tied arrays. 
 
+The rough perl equivalent is C<$myarray[$idx]>.
 =cut
 */