/
av.h
165 lines (125 loc) · 5.26 KB
/
av.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
/* av.h
*
* Copyright (C) 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000,
* 2001, 2002, 2005, 2006, 2007, 2008, by Larry Wall and others
*
* You may distribute under the terms of either the GNU General Public
* License or the Artistic License, as specified in the README file.
*
*/
struct xpvav {
HV* xmg_stash; /* class package */
union _xmgu xmg_u;
SSize_t xav_fill; /* Index of last element present */
SSize_t xav_max; /* max index for which array has space */
SV** xav_alloc; /* pointer to beginning of C array of SVs */
};
/* SV* xav_arylen; */
/* SVpav_REAL is set for all AVs whose xav_array contents are refcounted
* and initialized such that any element can be retrieved as a SV*.
* Such AVs may be referred to as "real" AVs. Examples include regular
* perl arrays, tiedarrays (since v5.16), and padlist AVs.
*
* Some things do not set SVpav_REAL, to indicate that they are cheating
* (for efficiency) by not refcounting the AV's contents or ensuring that
* all elements are safe for arbitrary access. This type of AV may be
* referred to as "fake" AVs. Examples include "@_" (unless tied), the
* scratchpad list, and the backrefs list on an object or stash.
*
* SVpav_REIFY is only meaningful on such "fake" AVs (i.e. where SVpav_REAL
* is not set). It indicates that the fake AV is capable of becoming
* real if the array needs to be modified in some way. Functions that
* modify fake AVs check both flags to call av_reify() as appropriate.
*
* av_reify() transforms a fake AV into a real one through two actions.
* Allocated but unpopulated elements are initialized to make them safe for
* arbitrary retrieval and the reference counts of populated elements are
* incremented.
*
* Note that the Perl stack has neither flag set. (Thus,
* items that go on the stack are never refcounted.)
*
* These internal details are subject to change any time. AV
* manipulations external to perl should not care about any of this.
* GSAR 1999-09-10
*/
/*
=for apidoc ADmnU||Nullav
Null AV pointer.
(deprecated - use C<(AV *)NULL> instead)
=for apidoc Am|SSize_t|AvFILL|AV* av
Same as C<L</av_top_index>> or C<L</av_tindex>>.
=for apidoc Cm|SSize_t|AvFILLp|AV* av
If the array C<av> is empty, this returns -1; otherwise it returns the maximum
value of the indices of all the array elements which are currently defined in
C<av>. It does not handle magic, hence the C<p> private indication in its name.
=for apidoc Am|SV**|AvARRAY|AV* av
Returns a pointer to the AV's internal SV* array.
This is useful for doing pointer arithmetic on the array.
If all you need is to look up an array element, then prefer C<av_fetch>.
=cut
*/
#ifndef PERL_CORE
# define Nullav Null(AV*)
#endif
#define AvARRAY(av) ((av)->sv_u.svu_array)
#define AvALLOC(av) ((XPVAV*) SvANY(av))->xav_alloc
#define AvMAX(av) ((XPVAV*) SvANY(av))->xav_max
#define AvFILLp(av) ((XPVAV*) SvANY(av))->xav_fill
#define AvARYLEN(av) (*Perl_av_arylen_p(aTHX_ MUTABLE_AV(av)))
#define AvREAL(av) (SvFLAGS(av) & SVpav_REAL)
#define AvREAL_on(av) (SvFLAGS(av) |= SVpav_REAL)
#define AvREAL_off(av) (SvFLAGS(av) &= ~SVpav_REAL)
#define AvREAL_only(av) (AvREIFY_off(av), SvFLAGS(av) |= SVpav_REAL)
#define AvREIFY(av) (SvFLAGS(av) & SVpav_REIFY)
#define AvREIFY_on(av) (SvFLAGS(av) |= SVpav_REIFY)
#define AvREIFY_off(av) (SvFLAGS(av) &= ~SVpav_REIFY)
#define AvREIFY_only(av) (AvREAL_off(av), SvFLAGS(av) |= SVpav_REIFY)
#define AvREALISH(av) (SvFLAGS(av) & (SVpav_REAL|SVpav_REIFY))
#define AvFILL(av) ((SvRMAGICAL((const SV *) (av))) \
? mg_size(MUTABLE_SV(av)) : AvFILLp(av))
#define av_top_index(av) AvFILL(av)
#define av_tindex(av) av_top_index(av)
/* Note that it doesn't make sense to do this:
* SvGETMAGIC(av); IV x = av_tindex_nomg(av);
*/
# define av_top_index_skip_len_mg(av) \
(__ASSERT_(SvTYPE(av) == SVt_PVAV) AvFILLp(av))
# define av_tindex_skip_len_mg(av) av_top_index_skip_len_mg(av)
#define NEGATIVE_INDICES_VAR "NEGATIVE_INDICES"
/*
=for apidoc newAV
Creates a new AV. The reference count is set to 1.
Perl equivalent: C<my @array;>.
=cut
*/
#define newAV() MUTABLE_AV(newSV_type(SVt_PVAV))
/*
=for apidoc newAV_alloc_x
=for apidoc newAV_alloc_xz
Similar to newAV(), but a SV* array is also allocated.
This is similar to but more efficient than doing:
AV *av = newAV();
av_extend(av, key);
Note that the actual size requested is allocated. This is unlike
av_extend(), which takes the maximum desired array index (AvMAX) as its
"key" parameter, and enforces a minimum value for that of 3.
In other words, the following examples all result in an array that can
fit four elements (indexes 0 .. 3):
AV *av = newAV();
av_extend(av, 1);
AV *av = newAV();
av_extend(av, 3);
AV *av = newAV_alloc_x(4);
Whereas this will result in an array that can only fit one element:
AV *av = newAV_alloc_x(1);
newAV_alloc_x does not initialize the array with NULL pointers.
newAV_alloc_xz does do that initialization.
These macros MUST NOT be called with a size less than 1.
=cut
*/
#define newAV_alloc_x(size) av_new_alloc(size,0)
#define newAV_alloc_xz(size) av_new_alloc(size,1)
/*
* ex: set ts=8 sts=4 sw=4 et:
*/