3 * Copyright (C) 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000,
4 * 2001, 2002, 2005, 2006, 2007, 2008, by Larry Wall and others
6 * You may distribute under the terms of either the GNU General Public
7 * License or the Artistic License, as specified in the README file.
12 HV* xmg_stash; /* class package */
14 SSize_t xav_fill; /* Index of last element present */
15 SSize_t xav_max; /* max index for which array has space */
16 SV** xav_alloc; /* pointer to beginning of C array of SVs */
21 /* SVpav_REAL is set for all AVs whose xav_array contents are refcounted
22 * and initialized such that any element can be retrieved as a SV*.
23 * Such AVs may be referred to as "real" AVs. Examples include regular
24 * perl arrays, tiedarrays (since v5.16), and padlist AVs.
26 * Some things do not set SVpav_REAL, to indicate that they are cheating
27 * (for efficiency) by not refcounting the AV's contents or ensuring that
28 * all elements are safe for arbitrary access. This type of AV may be
29 * referred to as "fake" AVs. Examples include "@_" (unless tied), the
30 * scratchpad list, and the backrefs list on an object or stash.
32 * SVpav_REIFY is only meaningful on such "fake" AVs (i.e. where SVpav_REAL
33 * is not set). It indicates that the fake AV is capable of becoming
34 * real if the array needs to be modified in some way. Functions that
35 * modify fake AVs check both flags to call av_reify() as appropriate.
37 * av_reify() transforms a fake AV into a real one through two actions.
38 * Allocated but unpopulated elements are initialized to make them safe for
39 * arbitrary retrieval and the reference counts of populated elements are
42 * Note that the Perl stack has neither flag set. (Thus,
43 * items that go on the stack are never refcounted.)
45 * These internal details are subject to change any time. AV
46 * manipulations external to perl should not care about any of this.
51 =for apidoc ADmnU||Nullav
54 (deprecated - use C<(AV *)NULL> instead)
56 =for apidoc Am|SSize_t|AvFILL|AV* av
57 Same as C<L</av_top_index>> or C<L</av_tindex>>.
59 =for apidoc Cm|SSize_t|AvFILLp|AV* av
61 If the array C<av> is empty, this returns -1; otherwise it returns the maximum
62 value of the indices of all the array elements which are currently defined in
63 C<av>. It does not handle magic, hence the C<p> private indication in its name.
65 =for apidoc Am|SV**|AvARRAY|AV* av
66 Returns a pointer to the AV's internal SV* array.
68 This is useful for doing pointer arithmetic on the array.
69 If all you need is to look up an array element, then prefer C<av_fetch>.
75 # define Nullav Null(AV*)
78 #define AvARRAY(av) ((av)->sv_u.svu_array)
79 #define AvALLOC(av) ((XPVAV*) SvANY(av))->xav_alloc
80 #define AvMAX(av) ((XPVAV*) SvANY(av))->xav_max
81 #define AvFILLp(av) ((XPVAV*) SvANY(av))->xav_fill
82 #define AvARYLEN(av) (*Perl_av_arylen_p(aTHX_ MUTABLE_AV(av)))
84 #define AvREAL(av) (SvFLAGS(av) & SVpav_REAL)
85 #define AvREAL_on(av) (SvFLAGS(av) |= SVpav_REAL)
86 #define AvREAL_off(av) (SvFLAGS(av) &= ~SVpav_REAL)
87 #define AvREAL_only(av) (AvREIFY_off(av), SvFLAGS(av) |= SVpav_REAL)
88 #define AvREIFY(av) (SvFLAGS(av) & SVpav_REIFY)
89 #define AvREIFY_on(av) (SvFLAGS(av) |= SVpav_REIFY)
90 #define AvREIFY_off(av) (SvFLAGS(av) &= ~SVpav_REIFY)
91 #define AvREIFY_only(av) (AvREAL_off(av), SvFLAGS(av) |= SVpav_REIFY)
94 #define AvREALISH(av) (SvFLAGS(av) & (SVpav_REAL|SVpav_REIFY))
96 #define AvFILL(av) ((SvRMAGICAL((const SV *) (av))) \
97 ? mg_size(MUTABLE_SV(av)) : AvFILLp(av))
98 #define av_top_index(av) AvFILL(av)
99 #define av_tindex(av) av_top_index(av)
101 /* Note that it doesn't make sense to do this:
102 * SvGETMAGIC(av); IV x = av_tindex_nomg(av);
104 # define av_top_index_skip_len_mg(av) \
105 (__ASSERT_(SvTYPE(av) == SVt_PVAV) AvFILLp(av))
106 # define av_tindex_skip_len_mg(av) av_top_index_skip_len_mg(av)
108 #define NEGATIVE_INDICES_VAR "NEGATIVE_INDICES"
112 Note that there are both real and fake AVs; see the beginning of this file and
116 =for apidoc_item newAV_alloc_x
117 =for apidoc_item newAV_alloc_xz
119 These all create a new AV, setting the reference count to 1. If you also know
120 the initial elements of the array with, see L</C<av_make>>.
122 As background, an array consists of three things:
128 A data structure containing information about the array as a whole, such as its
129 size and reference count.
133 A C language array of pointers to the individual elements. These are treated
134 as pointers to SVs, so all must be castable to SV*.
138 The individual elements themselves. These could be, for instance, SVs and/or
143 An empty array need only have the first data structure, and all these functions
144 create that. They differ in what else they do, as follows:
151 'form' above and below is because otherwise have two =items with the same name,
154 This does nothing beyond creating the whole-array data structure.
155 The Perl equivalent is approximately S<C<my @array;>>
157 This is useful when the minimum size of the array could be zero (perhaps there
158 are likely code paths that will entirely skip using it).
160 If the array does get used, the pointers data structure will need to be
161 allocated at that time. This will end up being done by L</av_extend>>,
166 or implicitly when the first element is stored:
168 (void)av_store(av, 0, sv);
170 Unused array elements are typically initialized by C<av_extend>.
172 =item C<newAV_alloc_x> form
174 This effectively does a C<newAV> followed by also allocating (uninitialized)
175 space for the pointers array. This is used when you know ahead of time the
176 likely minimum size of the array. It is more efficient to do this than doing a
177 plain C<newAV> followed by an C<av_extend>.
179 Of course the array can be extended later should it become necessary.
181 C<size> must be at least 1.
183 =item C<newAV_alloc_xz> form
185 This is C<newAV_alloc_x>, but initializes each pointer in it to NULL. This
186 gives added safety to guard against them being read before being set.
188 C<size> must be at least 1.
192 The following examples all result in an array that can fit four elements
198 AV *av = newAV_alloc_x(4);
200 AV *av = newAV_alloc_xz(4);
202 In contrast, the following examples allocate an array that is only guaranteed
203 to fit one element without extending:
205 AV *av = newAV_alloc_x(1);
206 AV *av = newAV_alloc_xz(1);
212 #define newAV() MUTABLE_AV(newSV_type(SVt_PVAV))
213 #define newAV_alloc_x(size) av_new_alloc(size,0)
214 #define newAV_alloc_xz(size) av_new_alloc(size,1)
217 * ex: set ts=8 sts=4 sw=4 et: