Add av_top() synonym for av_len()

av_len() is misleadingly named.

diff --git a/av.c b/av.c
index 475496d..366a848 100644 (file)
--- a/av.c
+++ b/av.c
@@ -759,25 +759,45 @@ Perl_av_shift(pTHX_ AV *av)
 }
 
 /*
-=for apidoc av_len
+=for apidoc av_top
 
 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.
+array is C<av_top(av) + 1>.  Returns -1 if the array is empty.
 
 The Perl equivalent for this is C<$#myarray>.
 
+=for apidoc av_len
+
+Same as L</av_top>.  Returns the highest index in the array.  Note that the
+return value is +1 what its name implies it returns; and hence differs in
+meaning from what the similarly named L</sv_len> returns.
+
 =cut
 */
 
 I32
 Perl_av_len(pTHX_ AV *av)
 {
+    /* If change this, must change identical Perl_av_top() just below */
+
     PERL_ARGS_ASSERT_AV_LEN;
     assert(SvTYPE(av) == SVt_PVAV);
 
     return AvFILL(av);
 }
 
+I32
+Perl_av_top(pTHX_ AV *av)
+{
+    /* So short, that it is just a duplicate of Perl_av_len().  Must keep them
+     * in sync */
+
+    PERL_ARGS_ASSERT_AV_TOP;
+    assert(SvTYPE(av) == SVt_PVAV);
+
+    return AvFILL(av);
+}
+
 /*
 =for apidoc av_fill
 

diff --git a/av.h b/av.h
index 35c921f..500fe5a 100644 (file)
--- a/av.h
+++ b/av.h
@@ -47,7 +47,7 @@ Null AV pointer.
 =head1 Array Manipulation Functions
 
 =for apidoc Am|int|AvFILL|AV* av
-Same as C<av_len()>.  Deprecated, use C<av_len()> instead.
+Same as C<av_top()>.  Deprecated, use C<av_top()> instead.
 
 =cut
 */

diff --git a/embed.fnc b/embed.fnc
index 0134357..b2b46f4 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -219,6 +219,7 @@ Apd |void   |av_push        |NN AV *av|NN SV *val
 EXp    |void   |av_reify       |NN AV *av
 ApdR   |SV*    |av_shift       |NN AV *av
 Apd    |SV**   |av_store       |NN AV *av|I32 key|NULLOK SV *val
+ApdR   |I32    |av_top         |NN AV *av
 Apd    |void   |av_undef       |NN AV *av
 ApdoxM |SV**   |av_create_and_unshift_one|NN AV **const avp|NN SV *const val
 Apd    |void   |av_unshift     |NN AV *av|I32 num

diff --git a/embed.h b/embed.h
index b2da778..e9a1980 100644 (file)
--- a/embed.h
+++ b/embed.h
@@ -56,6 +56,7 @@
 #define av_push(a,b)           Perl_av_push(aTHX_ a,b)
 #define av_shift(a)            Perl_av_shift(aTHX_ a)
 #define av_store(a,b,c)                Perl_av_store(aTHX_ a,b,c)
+#define av_top(a)              Perl_av_top(aTHX_ a)
 #define av_undef(a)            Perl_av_undef(aTHX_ a)
 #define av_unshift(a,b)                Perl_av_unshift(aTHX_ a,b)
 #define block_gimme()          Perl_block_gimme(aTHX)

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index f608dec..da75426 100644 (file)
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -374,7 +374,9 @@ well.
 
 =item *
 
-XXX
+A synonym for the misleadingly named C<av_len()> has been created:
+C<av_top()>.  Both of these return the number of the highest index in
+the array, not the number of elements it contains.
 
 =back
 

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 7bb5a06..52a0170 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -351,11 +351,11 @@ to these new elements.
 
 Here are some other functions:
 
-    I32   av_len(AV*);
+    I32   av_top(AV*);
     SV**  av_fetch(AV*, I32 key, I32 lval);
     SV**  av_store(AV*, I32 key, SV* val);
 
-The C<av_len> function returns the highest index value in an array (just
+The C<av_top> function returns the highest index value in an array (just
 like $#array in Perl).  If the array is empty, -1 is returned.  The
 C<av_fetch> function returns the value at index C<key>, but if C<lval>
 is non-zero, then C<av_fetch> will store an undef value at that index.

diff --git a/proto.h b/proto.h
index feae8a2..67eea1d 100644 (file)
--- a/proto.h
+++ b/proto.h
@@ -227,6 +227,12 @@ PERL_CALLCONV SV** Perl_av_store(pTHX_ AV *av, I32 key, SV *val)
 #define PERL_ARGS_ASSERT_AV_STORE      \
        assert(av)
 
+PERL_CALLCONV I32      Perl_av_top(pTHX_ AV *av)
+                       __attribute__warn_unused_result__
+                       __attribute__nonnull__(pTHX_1);
+#define PERL_ARGS_ASSERT_AV_TOP        \
+       assert(av)
+
 PERL_CALLCONV void     Perl_av_undef(pTHX_ AV *av)
                        __attribute__nonnull__(pTHX_1);
 #define PERL_ARGS_ASSERT_AV_UNDEF      \

diff --git a/regcomp.c b/regcomp.c
index 2084f53..a16b8b3 100644 (file)
--- a/regcomp.c
+++ b/regcomp.c
@@ -11478,7 +11478,6 @@ S_handle_sets(pTHX_ RExC_state_t *pRExC_state, I32 *flagp, U32 depth,
         no_close:
         FAIL("Syntax error in (?[...])");
     }
-#define av_top(a) av_len(a) /* XXX Temporary */
 
     /* Pass 2 only after this.  Everything in this construct is a
      * metacharacter.  Operands begin with either a '\' (for an escape