Array Manipulation Functions */

#include "EXTERN.h" #define PERL_IN_AV_C #include "perl.h"

void Perl_av_reify(pTHX_ AV *av) { dVAR; I32 key;

    PERL_ARGS_ASSERT_AV_REIFY;
    assert(SvTYPE(av) == SVt_PVAV);

    if (AvREAL(av))
	return;
#ifdef DEBUGGING
    if (SvTIED_mg((const SV *)av, PERL_MAGIC_tied) && ckWARN_d(WARN_DEBUGGING))
	Perl_warner(aTHX_ packWARN(WARN_DEBUGGING), "av_reify called on tied array");
#endif
    key = AvMAX(av) + 1;
    while (key > AvFILLp(av) + 1)
	AvARRAY(av)[--key] = &PL_sv_undef;
    while (key) {
	SV * const sv = AvARRAY(av)[--key];
	assert(sv);
	if (sv != &PL_sv_undef)
	    SvREFCNT_inc_simple_void_NN(sv);
    }
    key = AvARRAY(av) - AvALLOC(av);
    while (key)
	AvALLOC(av)[--key] = &PL_sv_undef;
    AvREIFY_off(av);
    AvREAL_on(av);
}

/* =for apidoc av_extend

Pre-extend an array. The key is the index to which the array should be extended.

Returns the SV at the specified index in the array. The key is the index. If lval is set then the fetch will be part of a store. Check that the return value is non-null before dereferencing it to a SV*.

See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more information on how to use this function on tied arrays.

Stores an SV in an array. The array index is specified as key. The return value will be NULL if the operation failed or if the value did not need to be actually stored within the array (as in the case of tied arrays). Otherwise it can be dereferenced to get the original SV*. Note that the caller is responsible for suitably incrementing the reference count of val before the call, and decrementing it if the function returned NULL.

See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more information on how to use this function on tied arrays.

Creates a new AV and populates it with a list of SVs. The SVs are copied into the array, so they may be freed after the call to av_make. The new AV will have a reference count of 1.

Clears an array, making it empty. Does not free the memory used by the array itself.

Undefines the array. Frees the memory used by the array itself.

Push an SV onto the end of the array, creating the array if necessary. A small internal helper function to remove a commonly duplicated idiom.

Pushes an SV onto the end of the array. The array will grow automatically to accommodate the addition. Like av_store, this takes ownership of one reference count.

Pops an SV off the end of the array. Returns &PL_sv_undef if the array is empty.

Unshifts an SV onto the beginning of the array, creating the array if necessary. A small internal helper function to remove a commonly duplicated idiom.

Unshift the given number of undef values onto the beginning of the array. The array will grow automatically to accommodate the addition. You must then use av_store to assign values to these new elements.

Shifts an SV off the beginning of the array. Returns &PL_sv_undef if the array is empty.

Returns the highest index in the array. The number of elements in the array is av_len(av) + 1. Returns -1 if the array is empty.

Set the highest index in the array to the given number, equivalent to Perl's $#array = $fill;.

The number of elements in the an array will be fill + 1 after av_fill() returns. If the array was previously shorter then the additional elements appended are set to PL_sv_undef. If the array was longer, then the excess elements are freed. av_fill(av, -1) is the same as av_clear(av).

Deletes the element indexed by key from the array. Returns the deleted element. If flags equals G_DISCARD, the element is freed and null is returned.

Returns true if the element indexed by key has been initialized.

This relies on the fact that uninitialized array elements are set to &PL_sv_undef.