Array Manipulation Functions */

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

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

    assert(av);

    if (AvREAL(av))
	return;
#ifdef DEBUGGING
    if (SvTIED_mg((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)
	    (void)SvREFCNT_inc(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. The reference count is set to 1.

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.

Pushes an SV onto the end of the array. The array will grow automatically to accommodate the addition.

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

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 the highest index in the array. Returns -1 if the array is empty.

Ensure than an array has a given number of elements, equivalent to Perl's $#array = $fill;.

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.