From: Gisle Aas <gisle@activestate.com>
Date: Mon, 30 Oct 2006 20:13:04 +0000 (+0000)
Subject: Improve documentation of av_len and av_fill.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=977a499b5acccfc647611cff52bb8688f262ea5c;p=p5sagit%2Fp5-mst-13.2.git

Improve documentation of av_len and av_fill.

p4raw-id: //depot/perl@29166
---

diff --git a/av.c b/av.c
index 3dfdf9a..e4ab13a 100644
--- a/av.c
+++ b/av.c
@@ -692,8 +692,8 @@ Perl_av_shift(pTHX_ register AV *av)
 /*
 =for apidoc av_len
 
-Returns the highest index in the array.  Returns -1 if the array is
-empty.
+Returns the highest index in the array.  The number of elements in the
+array is C<av_len(av) + 1>.  Returns -1 if the array is empty.
 
 =cut
 */
@@ -708,9 +708,15 @@ Perl_av_len(pTHX_ register const AV *av)
 /*
 =for apidoc av_fill
 
-Ensure than an array has a given number of elements, equivalent to
+Set the highest index in the array to the given number, equivalent to
 Perl's C<$#array = $fill;>.
 
+The number of elements in the an array will be C<fill + 1> after
+av_fill() returns.  If the array was previously shorter then the
+additional elements appended are set to C<PL_sv_undef>.  If the array
+was longer, then the excess elements are freed.  C<av_fill(av, -1)> is
+the same as C<av_clear(av)>.
+
 =cut
 */
 void