File Coverage

=for apidoc_section $AV
=for apidoc av_count
Returns the number of elements in the array C<av>.  This is the true length of
the array, including any undefined elements.  It is always the same as
S<C<av_top_index(av) + 1>>.

=cut

=for apidoc av_store_simple

This is a cut-down version of av_store that assumes that the array is
very straightforward - no magic, not readonly, and AvREAL - and that
C<key> is not negative. This function MUST NOT be used in situations
where any of those assumptions may not hold.

Stores an SV in an array.  The array index is specified as C<key>. It
can be dereferenced to get the C<SV*> that was stored there (= C<val>)).

Note that the caller is responsible for suitably incrementing the reference
count of C<val> before the call.

Approximate Perl equivalent: C<splice(@myarray, $key, 1, $val)>.

=cut

=for apidoc av_fetch_simple

This is a cut-down version of av_fetch that assumes that the array is
very straightforward - no magic, not readonly, and AvREAL - and that
C<key> is not negative. This function MUST NOT be used in situations
where any of those assumptions may not hold.

Returns the SV at the specified index in the array.  The C<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 C<SV*>.

The rough perl equivalent is C<$myarray[$key]>.

=cut

=for apidoc av_new_alloc

This implements L<perlapi/C<newAV_alloc_x>>
and L<perlapi/C<newAV_alloc_xz>>, which are the public API for this
functionality.

Creates a new AV and allocates its SV* array.

This is similar to, but more efficient than doing:

    AV *av = newAV();
    av_extend(av, key);

The size parameter is used to pre-allocate a SV* array large enough to
hold at least elements C<0..(size-1)>.  C<size> must be at least 1.

The C<zeroflag> parameter controls whether or not the array is NULL
initialized.

=cut

=for apidoc_section $CV
=for apidoc CvGV
Returns the GV associated with the CV C<sv>, reifying it if necessary.

=cut

=for apidoc CvDEPTH
Returns the recursion level of the CV C<sv>.  Hence >= 2 indicates we are in a
recursive call.

=cut

=for apidoc_section $rpp

=for apidoc rpp_extend
Ensures that there is space on the stack to push C<n> items, extending it
if necessary.

=cut

=for apidoc rpp_popfree_to

Pop and free all items on the argument stack above C<sp>. On return,
C<PL_stack_sp> will be equal to C<sp>.

=cut

=for apidoc rpp_popfree_to_NN

A variant of rpp_popfree_to() which assumes that all the pointers being
popped off the stack are non-NULL.

=cut

=for apidoc rpp_popfree_1

Pop and free the top item on the argument stack and update C<PL_stack_sp>.

=cut

=for apidoc rpp_popfree_1_NN

A variant of rpp_popfree_1() which assumes that the pointer being popped
off the stack is non-NULL.

=cut

=for apidoc rpp_popfree_2

Pop and free the top two items on the argument stack and update
C<PL_stack_sp>.

=cut

=for apidoc rpp_popfree_2_NN

A variant of rpp_popfree_2() which assumes that the two pointers being
popped off the stack are non-NULL.

=cut

=for apidoc rpp_pop_1_norc

Pop and return the top item off the argument stack and update
C<PL_stack_sp>. It's similar to rpp_popfree_1(), except that it actually
returns a value, and it I<doesn't> decrement the SV's reference count.
On non-C<PERL_RC_STACK> builds it actually increments the SV's reference
count.

This is useful in cases where the popped value is immediately embedded
somewhere e.g. via av_store(), allowing you skip decrementing and then
immediately incrementing the reference count again (and risk prematurely
freeing the SV if it had a RC of 1). On non-RC builds, the reference count
bookkeeping still works too, which is why it should be used rather than
a simple C<*PL_stack_sp-->.

=cut

=for apidoc      rpp_push_1
=for apidoc_item rpp_push_IMM
=for apidoc_item rpp_push_2
=for apidoc_item rpp_xpush_1
=for apidoc_item rpp_xpush_IMM
=for apidoc_item rpp_xpush_2

Push one or two SVs onto the stack, incrementing their reference counts
and updating C<PL_stack_sp>. With the C<x> variants, it extends the stack
first. The C<IMM> variants assume that the single argument is an immortal
such as <&PL_sv_undef> and, for efficiency, will skip incrementing its
reference count.

=cut

=for apidoc rpp_push_1_norc

Push C<sv> onto the stack without incrementing its reference count, and
update C<PL_stack_sp>. On non-PERL_RC_STACK builds, mortalise too.

This is most useful where an SV has just been created and already has a
reference count of 1, but has not yet been anchored anywhere.

=cut

=for apidoc      rpp_replace_1_1
=for apidoc_item rpp_replace_1_1_NN
=for apidoc_item rpp_replace_1_IMM_NN

Replace the current top stack item with C<sv>, while suitably adjusting
reference counts. Equivalent to rpp_popfree_1(); rpp_push_1(sv), but
is more efficient and handles both SVs being the same.

The C<_NN> variant assumes that the pointer on the stack to the SV being
freed is non-NULL.

The C<IMM_NN> variant is like the C<_NN> variant, but in addition, assumes
that the single argument is an immortal such as <&PL_sv_undef> and, for
efficiency, will skip incrementing its reference count.

=cut

=for apidoc      rpp_replace_2_1
=for apidoc_item rpp_replace_2_1_NN
=for apidoc_item rpp_replace_2_IMM_NN

Replace the current top to stacks item with C<sv>, while suitably
adjusting reference counts. Equivalent to rpp_popfree_2(); rpp_push_1(sv),
but is more efficient and handles SVs being the same.

The C<_NN> variant assumes that the pointers on the stack to the SVs being
freed are non-NULL.

The C<IMM_NN> variant is like the C<_NN> variant, but in addition, assumes
that the single argument is an immortal such as <&PL_sv_undef> and, for
efficiency, will skip incrementing its reference count.
=cut

=for apidoc rpp_replace_at

Replace the SV at address sp within the stack with C<sv>, while suitably
adjusting reference counts. Equivalent to C<*sp = sv>, except with proper
reference count handling.

=cut

=for apidoc rpp_replace_at_NN

A variant of rpp_replace_at() which assumes that the SV pointer on the
stack is non-NULL.

=cut

=for apidoc rpp_replace_at_norc

Replace the SV at address sp within the stack with C<sv>, while suitably
adjusting the reference count of the old SV. Equivalent to C<*sp = sv>,
except with proper reference count handling.

C<sv>'s reference count doesn't get incremented. On non-C<PERL_RC_STACK>
builds, it gets mortalised too.

This is most useful where an SV has just been created and already has a
reference count of 1, but has not yet been anchored anywhere.

=cut

=for apidoc rpp_replace_at_norc_NN

A variant of rpp_replace_at_norc() which assumes that the SV pointer on the
stack is non-NULL.

=cut

=for apidoc rpp_context

Impose void, scalar or list context on the stack.
First, pop C<extra> items off the stack, then when C<gimme> is:
C<G_LIST>:   return as-is.
C<G_VOID>:   pop everything back to C<mark>
C<G_SCALAR>: move the top stack item (or C<&PL_sv_undef> if none) to
C<mark+1> and free everything above it.

=cut

=for apidoc      rpp_try_AMAGIC_1
=for apidoc_item rpp_try_AMAGIC_2

Check whether either of the one or two SVs at the top of the stack is
magical or a ref, and in either case handle it specially: invoke get
magic, call an overload method, or replace a ref with a temporary numeric
value, as appropriate. If this function returns true, it indicates that
the correct return value is already on the stack. Intended to be used at
the beginning of the PP function for unary or binary ops.

=cut

=for apidoc rpp_stack_is_rc

Returns a boolean value indicating whether the stack is currently
reference-counted. Note that if the stack is split (bottom half RC, top
half non-RC), this function returns false, even if the top half currently
contains zero items.

=cut

=for apidoc rpp_is_lone

Indicates whether the stacked SV C<sv> (assumed to be not yet popped off
the stack) is only kept alive due to a single reference from the argument
stack and/or and the temps stack.

This can used for example to decide whether the copying of return values
in rvalue context can be skipped, or whether it shouldn't be assigned to
in lvalue context.

=cut

=for apidoc rpp_invoke_xs

Call the XS function associated with C<cv>. Wraps the call if necessary to
handle XS functions which are not aware of reference-counted stacks.

=cut

=for apidoc_section $unicode
*/

PERL_STATIC_INLINE void
Perl_append_utf8_from_native_byte(const U8 byte, U8** dest)
{
    /* Takes an input 'byte' (Latin1 or EBCDIC) and appends it to the UTF-8
     * encoded string at '*dest', updating '*dest' to include it */

    PERL_ARGS_ASSERT_APPEND_UTF8_FROM_NATIVE_BYTE;

    if (NATIVE_BYTE_IS_INVARIANT(byte))
        *((*dest)++) = byte;
    else {
        *((*dest)++) = UTF8_EIGHT_BIT_HI(byte);
        *((*dest)++) = UTF8_EIGHT_BIT_LO(byte);
    }
}

PERL_STATIC_INLINE U8 *
Perl_bytes_to_utf8(pTHX_ const U8 *s, STRLEN *lenp)
{
    return bytes_to_utf8_free_me(s, lenp, NULL);
}

PERL_STATIC_INLINE U8 *
Perl_bytes_to_utf8_temp_pv(pTHX_ const U8 *s, STRLEN *lenp)
{
    void * free_me = NULL;
    U8 * converted = bytes_to_utf8_free_me(s, lenp, &free_me);

    if (free_me) {
        SAVEFREEPV(free_me);
    }

    return converted;
}

PERL_STATIC_INLINE bool
Perl_utf8_to_bytes_new_pv(pTHX_ U8 const **s_ptr, STRLEN *lenp, void ** free_me)
{
    /* utf8_to_bytes_() is declared to take a non-const s_ptr because it may
     * change it, but NOT when called with PL_utf8_to_bytes_new_memory, so it
     * is ok to cast away const */
    return utf8_to_bytes_((U8 **) s_ptr, lenp, free_me,
                          PL_utf8_to_bytes_new_memory);
}

PERL_STATIC_INLINE bool
Perl_utf8_to_bytes_temp_pv(pTHX_ U8 const **s_ptr, STRLEN *lenp)
{
    /* utf8_to_bytes_() requires a non-NULL pointer, but doesn't use it when
     * called with PL_utf8_to_bytes_use_temporary */
    void* dummy = NULL;

    /* utf8_to_bytes_() is declared to take a non-const s_ptr because it may
     * change it, but NOT when called with PL_utf8_to_bytes_use_temporary, so
     * it is ok to cast away const */
    return utf8_to_bytes_((U8 **) s_ptr, lenp, &dummy,
                          PL_utf8_to_bytes_use_temporary);
}

PERL_STATIC_INLINE bool
Perl_utf8_to_bytes_overwrite(pTHX_ U8 **s_ptr, STRLEN *lenp)
{
    /* utf8_to_bytes_() requires a non-NULL pointer, but doesn't use it when
     * called with PL_utf8_to_bytes_overwrite */
    void* dummy = NULL;

    return utf8_to_bytes_(s_ptr, lenp, &dummy, PL_utf8_to_bytes_overwrite);
}

/*
=for apidoc valid_utf8_to_uvchr
Like C<L<perlapi/utf8_to_uv>>, but should only be called when it is
known that the next character in the input UTF-8 string C<s> is well-formed
(I<e.g.>, it passes C<L<perlapi/isUTF8_CHAR>>.  Surrogates, non-character code
points, and non-Unicode code points are allowed.

=cut

=for apidoc      is_utf8_invariant_string
=for apidoc_item is_utf8_invariant_string_loc
=for apidoc_item is_ascii_string
=for apidoc_item is_invariant_string

These each return TRUE if the first C<len> bytes of the string C<s> are the
same regardless of the UTF-8 encoding of the string (or UTF-EBCDIC encoding on
EBCDIC machines); otherwise they returns FALSE.  That is, they return TRUE if
they are UTF-8 invariant.  On ASCII-ish machines, all the ASCII characters and
only the ASCII characters fit this definition.  On EBCDIC machines, the
ASCII-range characters are invariant, but so also are the C1 controls.

If C<len> is 0, it will be calculated using C<strlen(s)>, (which means if you
use this option, that C<s> can't have embedded C<NUL> characters and has to
have a terminating C<NUL> byte).

All forms except C<is_utf8_invariant_string_loc> have identical behavior.  The
only difference with it is that it has an extra pointer parameter, C<ep>, into
which, if it isn't NULL, the location of the first UTF-8 variant character in
the C<ep> pointer will be stored upon failure.  If all characters are UTF-8
invariant, this function does not change the contents of C<*ep>.

C<is_invariant_string> is somewhat misleadingly named.
C<is_utf8_invariant_string> is preferred, as it indicates under what conditions
the string is invariant.

C<is_ascii_string> is misleadingly-named.  On ASCII-ish platforms, the name
isn't misleading: the ASCII-range characters are exactly the UTF-8 invariants.
But EBCDIC machines have more UTF-8 invariants than just the ASCII characters,
so the name C<is_utf8_invariant_string> is preferred.

See also
C<L</is_utf8_string>> and C<L</is_utf8_fixed_width_buf_flags>>.

=for apidoc_defn ARTm|bool|is_utf8_invariant_string|NN const U8 * const s|STRLEN len

=cut