X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/3f774658ecc4b04691265c9db31d70a4a611b290..02cf5fb76fa9ca5db8d1b04f9087dd6d0f81848e:/av.h diff --git a/av.h b/av.h index beed09d..6e0b24d 100644 --- a/av.h +++ b/av.h @@ -1,6 +1,7 @@ /* av.h * - * Copyright (c) 1991-2002, Larry Wall + * Copyright (C) 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000, + * 2001, 2002, 2005, 2006, 2007, 2008, by Larry Wall and others * * You may distribute under the terms of either the GNU General Public * License or the Artistic License, as specified in the README file. @@ -8,79 +9,210 @@ */ struct xpvav { - char* xav_array; /* pointer to first array element */ + HV* xmg_stash; /* class package */ + union _xmgu xmg_u; SSize_t xav_fill; /* Index of last element present */ SSize_t xav_max; /* max index for which array has space */ - IV xof_off; /* ptr is incremented by offset */ - NV xnv_nv; /* numeric value, if any */ - MAGIC* xmg_magic; /* magic for scalar array */ - HV* xmg_stash; /* class package */ - SV** xav_alloc; /* pointer to beginning of C array of SVs */ - SV* xav_arylen; - U8 xav_flags; }; +/* SV* xav_arylen; */ -/* AVf_REAL is set for all AVs whose xav_array contents are refcounted. - * Some things like "@_" and the scratchpad list do not set this, to - * indicate that they are cheating (for efficiency) by not refcounting - * the AV's contents. - * - * AVf_REIFY is only meaningful on such "fake" AVs (i.e. where AVf_REAL +/* SVpav_REAL is set for all AVs whose xav_array contents are refcounted + * and initialized such that any element can be retrieved as a SV*. + * Such AVs may be referred to as "real" AVs. Examples include regular + * perl arrays, tiedarrays (since v5.16), and padlist AVs. + * + * Some things do not set SVpav_REAL, to indicate that they are cheating + * (for efficiency) by not refcounting the AV's contents or ensuring that + * all elements are safe for arbitrary access. This type of AV may be + * referred to as "fake" AVs. Examples include "@_" (unless tied), the + * scratchpad list, and the backrefs list on an object or stash. + * + * SVpav_REIFY is only meaningful on such "fake" AVs (i.e. where SVpav_REAL * is not set). It indicates that the fake AV is capable of becoming * real if the array needs to be modified in some way. Functions that * modify fake AVs check both flags to call av_reify() as appropriate. * - * Note that the Perl stack and @DB::args have neither flag set. (Thus, + * av_reify() transforms a fake AV into a real one through two actions. + * Allocated but unpopulated elements are initialized to make them safe for + * arbitrary retrieval and the reference counts of populated elements are + * incremented. + * + * Note that the Perl stack has neither flag set. (Thus, * items that go on the stack are never refcounted.) * * These internal details are subject to change any time. AV * manipulations external to perl should not care about any of this. * GSAR 1999-09-10 */ -#define AVf_REAL 1 /* free old entries */ -#define AVf_REIFY 2 /* can become real */ - -/* XXX this is not used anywhere */ -#define AVf_REUSED 4 /* got undeffed--don't turn old memory into SVs now */ /* -=head1 Handy Values - -=for apidoc AmU||Nullav +=for apidoc ADmnU||Nullav Null AV pointer. -=head1 Array Manipulation Functions +(deprecated - use C<(AV *)NULL> instead) -=for apidoc Am|int|AvFILL|AV* av -Same as C. Deprecated, use C instead. +=for apidoc Am|SSize_t|AvFILL|AV* av +Same as C> or C>. + +=for apidoc Cm|SSize_t|AvFILLp|AV* av + +If the array C is empty, this returns -1; otherwise it returns the maximum +value of the indices of all the array elements which are currently defined in +C. It does not handle magic, hence the C

private indication in its name. + +=for apidoc Am|SV**|AvARRAY|AV* av +Returns a pointer to the AV's internal SV* array. + +This is useful for doing pointer arithmetic on the array. +If all you need is to look up an array element, then prefer C. =cut */ -#define Nullav Null(AV*) +#ifndef PERL_CORE +# define Nullav Null(AV*) +#endif -#define AvARRAY(av) ((SV**)((XPVAV*) SvANY(av))->xav_array) +#define AvARRAY(av) ((av)->sv_u.svu_array) #define AvALLOC(av) ((XPVAV*) SvANY(av))->xav_alloc #define AvMAX(av) ((XPVAV*) SvANY(av))->xav_max #define AvFILLp(av) ((XPVAV*) SvANY(av))->xav_fill -#define AvARYLEN(av) ((XPVAV*) SvANY(av))->xav_arylen -#define AvFLAGS(av) ((XPVAV*) SvANY(av))->xav_flags - -#define AvREAL(av) (AvFLAGS(av) & AVf_REAL) -#define AvREAL_on(av) (AvFLAGS(av) |= AVf_REAL) -#define AvREAL_off(av) (AvFLAGS(av) &= ~AVf_REAL) -#define AvREIFY(av) (AvFLAGS(av) & AVf_REIFY) -#define AvREIFY_on(av) (AvFLAGS(av) |= AVf_REIFY) -#define AvREIFY_off(av) (AvFLAGS(av) &= ~AVf_REIFY) -#define AvREUSED(av) (AvFLAGS(av) & AVf_REUSED) -#define AvREUSED_on(av) (AvFLAGS(av) |= AVf_REUSED) -#define AvREUSED_off(av) (AvFLAGS(av) &= ~AVf_REUSED) - -#define AvREALISH(av) (AvFLAGS(av) & (AVf_REAL|AVf_REIFY)) +#define AvARYLEN(av) (*Perl_av_arylen_p(aTHX_ MUTABLE_AV(av))) + +#define AvREAL(av) (SvFLAGS(av) & SVpav_REAL) +#define AvREAL_on(av) (SvFLAGS(av) |= SVpav_REAL) +#define AvREAL_off(av) (SvFLAGS(av) &= ~SVpav_REAL) +#define AvREAL_only(av) (AvREIFY_off(av), SvFLAGS(av) |= SVpav_REAL) +#define AvREIFY(av) (SvFLAGS(av) & SVpav_REIFY) +#define AvREIFY_on(av) (SvFLAGS(av) |= SVpav_REIFY) +#define AvREIFY_off(av) (SvFLAGS(av) &= ~SVpav_REIFY) +#define AvREIFY_only(av) (AvREAL_off(av), SvFLAGS(av) |= SVpav_REIFY) + + +#define AvREALISH(av) (SvFLAGS(av) & (SVpav_REAL|SVpav_REIFY)) -#define AvFILL(av) ((SvRMAGICAL((SV *) (av))) \ - ? mg_size((SV *) av) : AvFILLp(av)) +#define AvFILL(av) ((SvRMAGICAL((const SV *) (av))) \ + ? mg_size(MUTABLE_SV(av)) : AvFILLp(av)) +#define av_top_index(av) AvFILL(av) +#define av_tindex(av) av_top_index(av) + +/* Note that it doesn't make sense to do this: + * SvGETMAGIC(av); IV x = av_tindex_nomg(av); + */ +# define av_top_index_skip_len_mg(av) \ + (__ASSERT_(SvTYPE(av) == SVt_PVAV) AvFILLp(av)) +# define av_tindex_skip_len_mg(av) av_top_index_skip_len_mg(av) #define NEGATIVE_INDICES_VAR "NEGATIVE_INDICES" + +/* + +Note that there are both real and fake AVs; see the beginning of this file and +'av.c' + +=for apidoc newAV +=for apidoc_item newAV_alloc_x +=for apidoc_item newAV_alloc_xz + +These all create a new AV, setting the reference count to 1. If you also know +the initial elements of the array with, see L>. + +As background, an array consists of three things: + +=over + +=item 1. + +A data structure containing information about the array as a whole, such as its +size and reference count. + +=item 2. + +A C language array of pointers to the individual elements. These are treated +as pointers to SVs, so all must be castable to SV*. + +=item 3. + +The individual elements themselves. These could be, for instance, SVs and/or +AVs and/or HVs, etc. + +=back + +An empty array need only have the first data structure, and all these functions +create that. They differ in what else they do, as follows: + +=over + +=item C form + +=for comment +'form' above and below is because otherwise have two =items with the same name, +can't link to them. + +This does nothing beyond creating the whole-array data structure. +The Perl equivalent is approximately S> + +This is useful when the minimum size of the array could be zero (perhaps there +are likely code paths that will entirely skip using it). + +If the array does get used, the pointers data structure will need to be +allocated at that time. This will end up being done by L>, +either explicitly: + + av_extend(av, len); + +or implicitly when the first element is stored: + + (void)av_store(av, 0, sv); + +Unused array elements are typically initialized by C. + +=item C form + +This effectively does a C followed by also allocating (uninitialized) +space for the pointers array. This is used when you know ahead of time the +likely minimum size of the array. It is more efficient to do this than doing a +plain C followed by an C. + +Of course the array can be extended later should it become necessary. + +C must be at least 1. + +=item C form + +This is C, but initializes each pointer in it to NULL. This +gives added safety to guard against them being read before being set. + +C must be at least 1. + +=back + +The following examples all result in an array that can fit four elements +(indexes 0 .. 3): + + AV *av = newAV(); + av_extend(av, 3); + + AV *av = newAV_alloc_x(4); + + AV *av = newAV_alloc_xz(4); + +In contrast, the following examples allocate an array that is only guaranteed +to fit one element without extending: + + AV *av = newAV_alloc_x(1); + AV *av = newAV_alloc_xz(1); + +=cut + +*/ + +#define newAV() MUTABLE_AV(newSV_type(SVt_PVAV)) +#define newAV_alloc_x(size) av_new_alloc(size,0) +#define newAV_alloc_xz(size) av_new_alloc(size,1) + +/* + * ex: set ts=8 sts=4 sw=4 et: + */