1 /* av.h 2 * 3 * Copyright (C) 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000, 4 * 2001, 2002, 2005, 2006, 2007, 2008, by Larry Wall and others 5 * 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. 8 * 9 */ 10 11 struct xpvav { 12 HV* xmg_stash; /* class package */ 13 union _xmgu xmg_u; 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 */ 17 }; 18 19 /* SV* xav_arylen; */ 20 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. 25 * 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. 31 * 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. 36 * 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 40 * incremented. 41 * 42 * Note that the Perl stack has neither flag set. (Thus, 43 * items that go on the stack are never refcounted.) 44 * 45 * These internal details are subject to change any time. AV 46 * manipulations external to perl should not care about any of this. 47 * GSAR 1999-09-10 48 */ 49 50 /* 51 =for apidoc ADmnU||Nullav 52 Null AV pointer. 53 54 (deprecated - use C<(AV *)NULL> instead) 55 56 =for apidoc Am|SSize_t|AvFILL|AV* av 57 Same as C<L</av_top_index>> or C<L</av_tindex>>. 58 59 =for apidoc Cm|SSize_t|AvFILLp|AV* av 60 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. 64 65 =for apidoc Am|SV**|AvARRAY|AV* av 66 Returns a pointer to the AV's internal SV* array. 67 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>. 70 71 =cut 72 */ 73 74 #ifndef PERL_CORE 75 # define Nullav Null(AV*) 76 #endif 77 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))) 83 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) 92 93 94 #define AvREALISH(av) (SvFLAGS(av) & (SVpav_REAL|SVpav_REIFY)) 95 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) 100 101 /* Note that it doesn't make sense to do this: 102 * SvGETMAGIC(av); IV x = av_tindex_nomg(av); 103 */ 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) 107 108 #define NEGATIVE_INDICES_VAR "NEGATIVE_INDICES" 109 110 /* 111 112 Note that there are both real and fake AVs; see the beginning of this file and 113 'av.c' 114 115 =for apidoc newAV 116 =for apidoc_item newAV_mortal 117 =for apidoc_item newAV_alloc_x 118 =for apidoc_item newAV_alloc_xz 119 120 These all create a new AV, setting the reference count to 1. If you also know 121 the initial elements of the array with, see L</C<av_make>>. 122 123 As background, an array consists of three things: 124 125 =over 126 127 =item 1. 128 129 A data structure containing information about the array as a whole, such as its 130 size and reference count. 131 132 =item 2. 133 134 A C language array of pointers to the individual elements. These are treated 135 as pointers to SVs, so all must be castable to SV*. 136 137 =item 3. 138 139 The individual elements themselves. These could be, for instance, SVs and/or 140 AVs and/or HVs, etc. 141 142 =back 143 144 An empty array need only have the first data structure, and all these functions 145 create that. They differ in what else they do, as follows: 146 147 =over 148 149 =item C<newAV> form 150 151 =for comment 152 'form' above and below is because otherwise have two =items with the same name, 153 can't link to them. 154 155 This does nothing beyond creating the whole-array data structure. 156 The Perl equivalent is approximately S<C<my @array;>> 157 158 This is useful when the minimum size of the array could be zero (perhaps there 159 are likely code paths that will entirely skip using it). 160 161 If the array does get used, the pointers data structure will need to be 162 allocated at that time. This will end up being done by L</av_extend>>, 163 either explicitly: 164 165 av_extend(av, len); 166 167 or implicitly when the first element is stored: 168 169 (void)av_store(av, 0, sv); 170 171 Unused array elements are typically initialized by C<av_extend>. 172 173 =item C<newAV_mortal> form 174 175 This also creates the whole-array data structure, but also mortalises it. 176 (That is to say, a reference to the AV is added to the C<temps> stack.) 177 178 =item C<newAV_alloc_x> form 179 180 This effectively does a C<newAV> followed by also allocating (uninitialized) 181 space for the pointers array. This is used when you know ahead of time the 182 likely minimum size of the array. It is more efficient to do this than doing a 183 plain C<newAV> followed by an C<av_extend>. 184 185 Of course the array can be extended later should it become necessary. 186 187 C<size> must be at least 1. 188 189 =item C<newAV_alloc_xz> form 190 191 This is C<newAV_alloc_x>, but initializes each pointer in it to NULL. This 192 gives added safety to guard against them being read before being set. 193 194 C<size> must be at least 1. 195 196 =back 197 198 The following examples all result in an array that can fit four elements 199 (indexes 0 .. 3): 200 201 AV *av = newAV(); 202 av_extend(av, 3); 203 204 AV *av = newAV_alloc_x(4); 205 206 AV *av = newAV_alloc_xz(4); 207 208 In contrast, the following examples allocate an array that is only guaranteed 209 to fit one element without extending: 210 211 AV *av = newAV_alloc_x(1); 212 AV *av = newAV_alloc_xz(1); 213 214 =cut 215 216 */ 217 218 #define newAV() MUTABLE_AV(newSV_type(SVt_PVAV)) 219 #define newAV_mortal() MUTABLE_AV(newSV_type_mortal(SVt_PVAV)) 220 #define newAV_alloc_x(size) av_new_alloc(size,0) 221 #define newAV_alloc_xz(size) av_new_alloc(size,1) 222 223 /* 224 * ex: set ts=8 sts=4 sw=4 et: 225 */ 226