av.h

/*    av.h
 *
 *    Copyright (C) 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000,
 *    2001, 2002, 2005, 2006, 2007, 2008, by Larry Wall and others
 *
 *    You may distribute under the terms of either the GNU General Public
 *    License or the Artistic License, as specified in the README file.
 *
 */

struct xpvav {
    HV*		xmg_stash;	/* class package */
    union _xmgu	xmg_u;
    SSize_t	xav_fill;       /* Index of last element present */
    SSize_t	xav_max;        /* max index for which array has space */
    SV**	xav_alloc;	/* pointer to beginning of C array of SVs */
};

/* SV*	xav_arylen; */

/* SVpav_REAL is set for all AVs whose xav_array contents are refcounted
 * and initialized such that any element can be retrieved as a SV*.
 * Such AVs may be referred to as "real" AVs. Examples include regular
 * perl arrays, tiedarrays (since v5.16), and padlist AVs.
 *
 * Some things do not set SVpav_REAL, to indicate that they are cheating
 * (for efficiency) by not refcounting the AV's contents or ensuring that
 * all elements are safe for arbitrary access. This type of AV may be
 * referred to as "fake" AVs. Examples include "@_" (unless tied), the
 * scratchpad list, and the backrefs list on an object or stash.
 *
 * SVpav_REIFY is only meaningful on such "fake" AVs (i.e. where SVpav_REAL
 * is not set).  It indicates that the fake AV is capable of becoming
 * real if the array needs to be modified in some way.  Functions that
 * modify fake AVs check both flags to call av_reify() as appropriate.
 *
 * av_reify() transforms a fake AV into a real one through two actions.
 * Allocated but unpopulated elements are initialized to make them safe for
 * arbitrary retrieval and the reference counts of populated elements are
 * incremented.
 *
 * Note that the Perl stack has neither flag set. (Thus,
 * items that go on the stack are never refcounted.)
 *
 * These internal details are subject to change any time.  AV
 * manipulations external to perl should not care about any of this.
 * GSAR 1999-09-10
 */

/*
=for apidoc ADmnU||Nullav
Null AV pointer.

(deprecated - use C<(AV *)NULL> instead)

=for apidoc Am|SSize_t|AvFILL|AV* av
Same as C<L</av_top_index>> or C<L</av_tindex>>.

=for apidoc Cm|SSize_t|AvFILLp|AV* av

If the array C<av> is empty, this returns -1; otherwise it returns the maximum
value of the indices of all the array elements which are currently defined in
C<av>.  It does not handle magic, hence the C<p> private indication in its name.

=for apidoc Am|SV**|AvARRAY|AV* av
Returns a pointer to the AV's internal SV* array.

This is useful for doing pointer arithmetic on the array.
If all you need is to look up an array element, then prefer C<av_fetch>.

=cut
*/

#ifndef PERL_CORE
#  define Nullav Null(AV*)
#endif

#define AvARRAY(av)	((av)->sv_u.svu_array)
#define AvALLOC(av)	((XPVAV*)  SvANY(av))->xav_alloc
#define AvMAX(av)	((XPVAV*)  SvANY(av))->xav_max
#define AvFILLp(av)	((XPVAV*)  SvANY(av))->xav_fill
#define AvARYLEN(av)	(*Perl_av_arylen_p(aTHX_ MUTABLE_AV(av)))

#define AvREAL(av)	(SvFLAGS(av) & SVpav_REAL)
#define AvREAL_on(av)	(SvFLAGS(av) |= SVpav_REAL)
#define AvREAL_off(av)	(SvFLAGS(av) &= ~SVpav_REAL)
#define AvREAL_only(av)	(AvREIFY_off(av), SvFLAGS(av) |= SVpav_REAL)
#define AvREIFY(av)	(SvFLAGS(av) & SVpav_REIFY)
#define AvREIFY_on(av)	(SvFLAGS(av) |= SVpav_REIFY)
#define AvREIFY_off(av)	(SvFLAGS(av) &= ~SVpav_REIFY)
#define AvREIFY_only(av)	(AvREAL_off(av), SvFLAGS(av) |= SVpav_REIFY)


#define AvREALISH(av)	(SvFLAGS(av) & (SVpav_REAL|SVpav_REIFY))
                                          
#define AvFILL(av)	((SvRMAGICAL((const SV *) (av))) \
                         ? mg_size(MUTABLE_SV(av)) : AvFILLp(av))
#define av_top_index(av) AvFILL(av)
#define av_tindex(av)    av_top_index(av)

/* Note that it doesn't make sense to do this:
 *      SvGETMAGIC(av); IV x = av_tindex_nomg(av);
 */
#   define av_top_index_skip_len_mg(av)                                     \
                            (__ASSERT_(SvTYPE(av) == SVt_PVAV) AvFILLp(av))
#   define av_tindex_skip_len_mg(av)  av_top_index_skip_len_mg(av)

#define NEGATIVE_INDICES_VAR "NEGATIVE_INDICES"

/*
=for apidoc newAV
=for apidoc_item newAV_alloc_x
=for apidoc_item newAV_alloc_xz

These all create a new AV, setting the reference count to 1. They differ
in the allocation and population of the array of SV*s that always
accompanies a non-empty AV.

The Perl equivalent is approximately C<my @array;>.

newAV does not allocate a SV* array.
    AV *av = newAV();

This is very useful when an AV is required, but populating it may be
deferred, or even never actually take place. (Memory is not allocated
unnecessarily.)

Subsequent SV* array allocation would be performed via C<L</av_extend>>.
This might be called directly:
    av_extend(av, key);

Or it might be called implicitly when the first element is stored:
    (void)av_store(av, 0, sv);

Unused array elements are typically initialized by C<av_extend>. (Only
core maintainers should have need to concern themseleves with when that
is not the case. Refer to F<av.h> and F<av.c> for the differences between
real and fake AVs.)

In contrast, when an AV is created for immediate population with a known
(or likely) number of elements, it is more efficient to immediately
allocate a SV* array of the necessary size. (This avoids inefficient use
of C<av_extend> and the potential for the first allocation being too small
and then having to resize it.)

For that scenario, newAV_alloc_x and newAV_alloc_xz can be used to create
an AV and allocate a SV* array to fit the specified number of elements.
(As a result, these macros MUST NOT be called with a size less than 1.)

newAV_alloc_x does not initialize the array elements - and so the
expectation is that all will be initialized elsewhere prior to any
potentials reads. newAV_alloc_xz does initialize the array elements.

The following examples all result in an array that can fit four elements
(indexes 0 .. 3):

    AV *av = newAV();
    av_extend(av, 1);

    AV *av = newAV();
    av_extend(av, 3);

    AV *av = newAV_alloc_xz(4);

    AV *av = newAV_alloc_x(4);

In the newAV_alloc_x case, the array elements will not be initialized
and their contents are therefore undefined. In the other cases, the
array elements are all initialized.

In contrast, the following examples allocate an SV* array that is only
guaranteed to fit one element:

    AV *av = newAV_alloc_x(1);
    AV *av = newAV_alloc_xz(1);

=cut
*/

#define newAV()	MUTABLE_AV(newSV_type(SVt_PVAV))
#define newAV_alloc_x(size)  av_new_alloc(size,0)
#define newAV_alloc_xz(size) av_new_alloc(size,1)

/*
 * ex: set ts=8 sts=4 sw=4 et:
 */