av.h

   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  */