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))
        Perl_ck_warner_d(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 true, you are guaranteed to get a real SV back (in case it wasn't real before), which you can then modify. 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.

The rough perl equivalent is $myarray[$idx].

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 SV* that was stored there (= val)).

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.

Approximate Perl equivalent: $myarray[$key] = $val;.

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.

Perl equivalent: my @new_array = ($scalar1, $scalar2, $scalar3...);

Clears an array, making it empty. Does not free the memory the av uses to store its list of scalars. If any destructors are triggered as a result, the av itself may be freed when this function returns.

Perl equivalent: @myarray = ();.

Undefines the array. Frees the memory used by the av to store its list of scalars. If any destructors are triggered as a result, the av itself may be freed.

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. This takes ownership of one reference count.

Perl equivalent: push @myarray, $elem;.

Removes one SV from the end of the array, reducing its size by one and returning the SV (transferring control of one reference count) to the caller. Returns &PL_sv_undef if the array is empty.

Perl equivalent: pop(@myarray);

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.

Perl equivalent: unshift @myarray, ( (undef) x $n );

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

Perl equivalent: shift(@myarray);

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

The Perl equivalent for this is $#myarray.

(A slightly shorter form is av_tindex.)

Same as "av_top_index". Returns the highest index in the array. Note that the return value is +1 what its name implies it returns; and hence differs in meaning from what the similarly named "sv_len" returns.

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, makes the element mortal, and returns it. If flags equals G_DISCARD, the element is freed and null is returned. Perl equivalent: my $elem = delete($myarray[$idx]); for the non-G_DISCARD version and a void-context delete($myarray[$idx]); for the G_DISCARD version.

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.

Perl equivalent: exists($myarray[$key]).

cpanm vars

perl -MCPAN -e shell
install vars