perlapi.pod Enhancements

This is a patch to enhance perlapi.pod by providing Perl equivalents and
clarifying documentation where appropriate.

1 files changed, 14 insertions, 2 deletions

diff --git a/av.c b/av.c
index 9dd4a76b29..e6b9d22767 100644
--- a/av.c
+++ b/av.c
@@ -275,11 +275,15 @@ Perl_av_fetch(pTHX_ register AV *av, I32 key, I32 lval)
 Stores an SV in an array.  The array index is specified as C<key>.  The
 return value will be NULL if the operation failed or if the value did not
 need to be actually stored within the array (as in the case of tied
-arrays). Otherwise it can be dereferenced to get the original C<SV*>.  Note
-that the caller is responsible for suitably incrementing the reference
+arrays). Otherwise, it can be dereferenced to get the C<SV*> that was stored
+there (= C<val>)).
+
+Note that the caller is responsible for suitably incrementing the reference
 count of C<val> before the call, and decrementing it if the function
 returned NULL.
 
+Approximate Perl equivalent: C<$myarray[$key] = $val;>.
+
 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
 more information on how to use this function on tied arrays.
 
@@ -529,6 +533,8 @@ Perl_av_create_and_push(pTHX_ AV **const avp, SV *const val)
 Pushes an SV onto the end of the array.  The array will grow automatically
 to accommodate the addition. This takes ownership of one reference count.
 
+Perl equivalent: C<push @myarray, $elem;>.
+
 =cut
 */
 
@@ -558,6 +564,8 @@ Perl_av_push(pTHX_ register AV *av, SV *val)
 Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
 is empty.
 
+Perl equivalent: C<pop(@myarray);>
+
 =cut
 */
 
@@ -617,6 +625,8 @@ Unshift the given number of C<undef> values onto the beginning of the
 array.  The array will grow automatically to accommodate the addition.  You
 must then use C<av_store> to assign values to these new elements.
 
+Perl equivalent: C<unshift @myarray, ( (undef) x $n );>
+    
 =cut
 */
 
@@ -679,6 +689,8 @@ Perl_av_unshift(pTHX_ register AV *av, register I32 num)
 Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the 
 array is empty.
 
+Perl equivalent: C<shift(@myarray);>
+
 =cut
 */