Pre-extend an array so that it is capable of storing values at indexes 0..key. Thus av_extend(av,99) guarantees that the array can store 100 elements, i.e. that av_store(av, 0, sv) through av_store(av, 99, sv) on a plain array will work without any further memory allocation.

If the av argument is a tied array then will call the EXTEND tied array method with an argument of (key+1).

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 (**strp, length size) of SVs. A copy is made of each SV, so their refcounts are not changed. The new AV will have a reference count of 1.

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

Creates a new AV and populates it with values copied from an existing AV. The new AV will have a reference count of 1, and will contain newly created SVs copied from the original SV. The original source will remain unchanged.

Perl equivalent: my @new_array = @existing_array;

Creates a new AV and populates it with keys and values copied from an existing HV. The new AV will have a reference count of 1, and will contain newly created SVs copied from the original HV. The original source will remain unchanged.

Perl equivalent: my @new_array = %existing_hash;

Frees 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);

These behave identically. If the array av is empty, these return -1; otherwise they return the maximum value of the indices of all the array elements which are currently defined in av.

They process 'get' magic.

The Perl equivalent for these is $#av.

Use "av_count" to get the number of elements in an array.

Same as "av_top_index". Note that, unlike what the name implies, it returns the maximum index in the array. This is unlike "sv_len", which returns what you would expect.

To get the true number of elements in the array, instead use "av_count".

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