These all increment the reference count of the given SV, which must be an AV. They are useful when assigning the result into a typed pointer as they avoid the need to cast the result to the appropriate type.

(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. If you also know the initial elements of the array with, see "av_make".

As background, an array consists of three things:

1. A data structure containing information about the array as a whole, such as its size and reference count.

2. A C language array of pointers to the individual elements. These are treated as pointers to SVs, so all must be castable to SV*.

3. The individual elements themselves. These could be, for instance, SVs and/or AVs and/or HVs, etc.

An empty array need only have the first data structure, and all these functions create that. They differ in what else they do, as follows:

newAV form

This does nothing beyond creating the whole-array data structure. The Perl equivalent is approximately my @array;

This is useful when the minimum size of the array could be zero (perhaps there are likely code paths that will entirely skip using it).

If the array does get used, the pointers data structure will need to be allocated at that time. This will end up being done by "av_extend">, either explicitly:

av_extend(av, len);

or implicitly when the first element is stored:

(void)av_store(av, 0, sv);

Unused array elements are typically initialized by av_extend.

newAV_mortal form

This also creates the whole-array data structure, but also mortalises it. (That is to say, a reference to the AV is added to the temps stack.)

newAV_alloc_x form

This effectively does a newAV followed by also allocating (uninitialized) space for the pointers array. This is used when you know ahead of time the likely minimum size of the array. It is more efficient to do this than doing a plain newAV followed by an av_extend.

Of course the array can be extended later should it become necessary.

size must be at least 1.

newAV_alloc_xz form

This is newAV_alloc_x, but initializes each pointer in it to NULL. This gives added safety to guard against them being read before being set.

size must be at least 1.

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

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

AV *av = newAV_alloc_x(4);

AV *av = newAV_alloc_xz(4);

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

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