Array Manipulation Functions */

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

void Perl_av_reify(pTHX_ AV *av) { SSize_t 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] = NULL;
    while (key) {
        SV * const sv = AvARRAY(av)[--key];
        if (sv != &PL_sv_undef)
            SvREFCNT_inc_simple_void(sv);
    }
    key = AvARRAY(av) - AvALLOC(av);
    while (key)
        AvALLOC(av)[--key] = NULL;
    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[$key].

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: splice(@myarray, $key, 1, $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...);

Frees the all the elements of an array, leaving it empty. The XS equivalent of @array = (). See also "av_undef".

Note that it is possible that the actions of a destructor called directly or indirectly by freeing an element of the array could cause the reference count of the array itself to be reduced (e.g. by deleting an entry in the symbol table). So it is a possibility that the AV could have been freed (or even reallocated) on return from the call unless you hold a reference to it.

Undefines the array. The XS equivalent of undef(@array).

As well as freeing all the elements of the array (like av_clear()), this also frees the memory used by the av to store its list of scalars.

See "av_clear" for a note about the array possibly being invalid on return.

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 (transferring control of one reference count) onto the end of the array. The array will grow automatically to accommodate the addition.

Perl equivalent: push @myarray, $val;.

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.

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

Removes one SV from the start 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: 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". Note that, unlike what the name implies, it returns the highest index in the array, so to get the size of the array you need to use av_len(av) + 1. This is unlike "sv_len", which returns what you would expect.

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

The number of elements in the array will be fill + 1 after av_fill() returns. If the array was previously shorter, then the additional elements appended are set to NULL. 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. NULL is also returned if key is out of range.

Perl equivalent: splice(@myarray, $key, 1, undef) (with the splice in void context if G_DISCARD is present).

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

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

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

cpanm less

perl -MCPAN -e shell
install less