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 =for apidoc newAV
 112 =for apidoc_item newAV_alloc_x
 113 =for apidoc_item newAV_alloc_xz
 114
 115 These all create a new AV, setting the reference count to 1. They differ
 116 in the allocation and population of the array of SV*s that always
 117 accompanies a non-empty AV.
 118
 119 The Perl equivalent is approximately C<my @array;>.
 120
 121 newAV does not allocate a SV* array.
 122     AV *av = newAV();
 123
 124 This is very useful when an AV is required, but populating it may be
 125 deferred, or even never actually take place. (Memory is not allocated
 126 unnecessarily.)
 127
 128 Subsequent SV* array allocation would be performed via C<L</av_extend>>.
 129 This might be called directly:
 130     av_extend(av, key);
 131
 132 Or it might be called implicitly when the first element is stored:
 133     (void)av_store(av, 0, sv);
 134
 135 Unused array elements are typically initialized by C<av_extend>. (Only
 136 core maintainers should have need to concern themseleves with when that
 137 is not the case. Refer to F<av.h> and F<av.c> for the differences between
 138 real and fake AVs.)
 139
 140 In contrast, when an AV is created for immediate population with a known
 141 (or likely) number of elements, it is more efficient to immediately
 142 allocate a SV* array of the necessary size. (This avoids inefficient use
 143 of C<av_extend> and the potential for the first allocation being too small
 144 and then having to resize it.)
 145
 146 For that scenario, newAV_alloc_x and newAV_alloc_xz can be used to create
 147 an AV and allocate a SV* array to fit the specified number of elements.
 148 (As a result, these macros MUST NOT be called with a size less than 1.)
 149
 150 newAV_alloc_x does not initialize the array elements - and so the
 151 expectation is that all will be initialized elsewhere prior to any
 152 potentials reads. newAV_alloc_xz does initialize the array elements.
 153
 154 The following examples all result in an array that can fit four elements
 155 (indexes 0 .. 3):
 156
 157     AV *av = newAV();
 158     av_extend(av, 1);
 159
 160     AV *av = newAV();
 161     av_extend(av, 3);
 162
 163     AV *av = newAV_alloc_xz(4);
 164
 165     AV *av = newAV_alloc_x(4);
 166
 167 In the newAV_alloc_x case, the array elements will not be initialized
 168 and their contents are therefore undefined. In the other cases, the
 169 array elements are all initialized.
 170
 171 In contrast, the following examples allocate an SV* array that is only
 172 guaranteed to fit one element:
 173
 174     AV *av = newAV_alloc_x(1);
 175     AV *av = newAV_alloc_xz(1);
 176
 177 =cut
 178 */
 179
 180 #define newAV() MUTABLE_AV(newSV_type(SVt_PVAV))
 181 #define newAV_alloc_x(size)  av_new_alloc(size,0)
 182 #define newAV_alloc_xz(size) av_new_alloc(size,1)
 183
 184 /*
 185  * ex: set ts=8 sts=4 sw=4 et:
 186  */