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_alloc_x 117 =for apidoc_item newAV_alloc_xz 118 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>>. 121 122 As background, an array consists of three things: 123 124 =over 125 126 =item 1. 127 128 A data structure containing information about the array as a whole, such as its 129 size and reference count. 130 131 =item 2. 132 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*. 135 136 =item 3. 137 138 The individual elements themselves. These could be, for instance, SVs and/or 139 AVs and/or HVs, etc. 140 141 =back 142 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: 145 146 =over 147 148 =item C<newAV> form 149 150 =for comment 151 'form' above and below is because otherwise have two =items with the same name, 152 can't link to them. 153 154 This does nothing beyond creating the whole-array data structure. 155 The Perl equivalent is approximately S<C<my @array;>> 156 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). 159 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>>, 162 either explicitly: 163 164 av_extend(av, len); 165 166 or implicitly when the first element is stored: 167 168 (void)av_store(av, 0, sv); 169 170 Unused array elements are typically initialized by C<av_extend>. 171 172 =item C<newAV_alloc_x> form 173 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>. 178 179 Of course the array can be extended later should it become necessary. 180 181 C<size> must be at least 1. 182 183 =item C<newAV_alloc_xz> form 184 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. 187 188 C<size> must be at least 1. 189 190 =back 191 192 The following examples all result in an array that can fit four elements 193 (indexes 0 .. 3): 194 195 AV *av = newAV(); 196 av_extend(av, 3); 197 198 AV *av = newAV_alloc_x(4); 199 200 AV *av = newAV_alloc_xz(4); 201 202 In contrast, the following examples allocate an array that is only guaranteed 203 to fit one element without extending: 204 205 AV *av = newAV_alloc_x(1); 206 AV *av = newAV_alloc_xz(1); 207 208 =cut 209 210 */ 211 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) 215 216 /* 217 * ex: set ts=8 sts=4 sw=4 et: 218 */ 219