(deprecated - use (AV *)NULL instead)

If the array 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 av. It does not handle magic, hence the p private indication in its name.

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

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 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 "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 av_extend. (Only core maintainers should have need to concern themseleves with when that is not the case. Refer to av.h and 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 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);