This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
path_is_absolute() needs a prototype (and maybe
[perl5.git] / hv.h
CommitLineData
a0d0e21e 1/* hv.h
79072805 2 *
bc89e66f 3 * Copyright (c) 1991-2001, Larry Wall
79072805
LW
4 *
5 * You may distribute under the terms of either the GNU General Public
6 * License or the Artistic License, as specified in the README file.
7 *
79072805
LW
8 */
9
5cbe4eec 10/* typedefs to eliminate some typing */
79072805 11typedef struct he HE;
ff68c719 12typedef struct hek HEK;
79072805 13
5cbe4eec 14/* entry in hash value chain */
79072805 15struct he {
5cbe4eec
MF
16 HE *hent_next; /* next entry in chain */
17 HEK *hent_hek; /* hash key */
18 SV *hent_val; /* scalar value that was hashed */
bbce6d69
PP
19};
20
5cbe4eec 21/* hash key -- defined separately for use as shared pointer */
ff68c719 22struct hek {
5cbe4eec
MF
23 U32 hek_hash; /* hash of key */
24 I32 hek_len; /* length of hash key */
25 char hek_key[1]; /* variable-length hash key */
79072805
LW
26};
27
5cbe4eec 28/* hash structure: */
6ee623d5 29/* This structure must match the beginning of struct xpvmg in sv.h. */
79072805 30struct xpvhv {
463ee0b2
LW
31 char * xhv_array; /* pointer to malloced string */
32 STRLEN xhv_fill; /* how full xhv_array currently is */
33 STRLEN xhv_max; /* subscript of last element of xhv_array */
6ee623d5 34 IV xhv_keys; /* how many elements in the array */
65202027 35 NV xnv_nv; /* numeric value, if any */
8aacddc1 36#define xhv_placeholders xnv_nv
79072805
LW
37 MAGIC* xmg_magic; /* magic for scalar array */
38 HV* xmg_stash; /* class package */
39
79072805
LW
40 I32 xhv_riter; /* current root of iterator */
41 HE *xhv_eiter; /* current entry of iterator */
42 PMOP *xhv_pmroot; /* list of pm's for this package */
43 char *xhv_name; /* name, if a symbol table */
79072805
LW
44};
45
5cbe4eec 46/* hash a key */
a6fe520e
MF
47/* FYI: This is the "One-at-a-Time" algorithm by Bob Jenkins */
48/* from requirements by Colin Plumb. */
49/* (http://burtleburtle.net/bob/hash/doobs.html) */
bf6bd887
PP
50#define PERL_HASH(hash,str,len) \
51 STMT_START { \
08105a92 52 register const char *s_PeRlHaSh = str; \
bf6bd887
PP
53 register I32 i_PeRlHaSh = len; \
54 register U32 hash_PeRlHaSh = 0; \
a6fe520e
MF
55 while (i_PeRlHaSh--) { \
56 hash_PeRlHaSh += *s_PeRlHaSh++; \
57 hash_PeRlHaSh += (hash_PeRlHaSh << 10); \
58 hash_PeRlHaSh ^= (hash_PeRlHaSh >> 6); \
59 } \
60 hash_PeRlHaSh += (hash_PeRlHaSh << 3); \
61 hash_PeRlHaSh ^= (hash_PeRlHaSh >> 11); \
4fee5c71 62 (hash) = (hash_PeRlHaSh + (hash_PeRlHaSh << 15)); \
bf6bd887
PP
63 } STMT_END
64
954c1994 65/*
ccfc67b7
JH
66=head1 Hash Manipulation Functions
67
954c1994
GS
68=for apidoc AmU||HEf_SVKEY
69This flag, used in the length slot of hash entries and magic structures,
d1be9408 70specifies the structure contains an C<SV*> pointer where a C<char*> pointer
954c1994
GS
71is to be expected. (For information only--not to be used).
72
ccfc67b7
JH
73=head1 Handy Values
74
954c1994
GS
75=for apidoc AmU||Nullhv
76Null HV pointer.
77
ccfc67b7
JH
78=head1 Hash Manipulation Functions
79
954c1994
GS
80=for apidoc Am|char*|HvNAME|HV* stash
81Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
82
83=for apidoc Am|void*|HeKEY|HE* he
84Returns the actual pointer stored in the key slot of the hash entry. The
85pointer may be either C<char*> or C<SV*>, depending on the value of
86C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
87usually preferable for finding the value of a key.
88
89=for apidoc Am|STRLEN|HeKLEN|HE* he
90If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
91holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
92be assigned to. The C<HePV()> macro is usually preferable for finding key
93lengths.
94
95=for apidoc Am|SV*|HeVAL|HE* he
96Returns the value slot (type C<SV*>) stored in the hash entry.
97
98=for apidoc Am|U32|HeHASH|HE* he
99Returns the computed hash stored in the hash entry.
100
101=for apidoc Am|char*|HePV|HE* he|STRLEN len
102Returns the key slot of the hash entry as a C<char*> value, doing any
103necessary dereferencing of possibly C<SV*> keys. The length of the string
104is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
105not care about what the length of the key is, you may use the global
106variable C<PL_na>, though this is rather less efficient than using a local
107variable. Remember though, that hash keys in perl are free to contain
108embedded nulls, so using C<strlen()> or similar is not a good way to find
109the length of hash keys. This is very similar to the C<SvPV()> macro
110described elsewhere in this document.
111
112=for apidoc Am|SV*|HeSVKEY|HE* he
113Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
114contain an C<SV*> key.
115
116=for apidoc Am|SV*|HeSVKEY_force|HE* he
117Returns the key as an C<SV*>. Will create and return a temporary mortal
118C<SV*> if the hash entry contains only a C<char*> key.
119
120=for apidoc Am|SV*|HeSVKEY_set|HE* he|SV* sv
121Sets the key to a given C<SV*>, taking care to set the appropriate flags to
122indicate the presence of an C<SV*> key, and returns the same
123C<SV*>.
124
125=cut
126*/
bf6bd887 127
bf5b86ae 128/* these hash entry flags ride on hent_klen (for use only in magic/tied HVs) */
d1be9408 129#define HEf_SVKEY -2 /* hent_key is an SV* */
bf6bd887
PP
130
131
79072805 132#define Nullhv Null(HV*)
4efcf9a2 133#define HvARRAY(hv) (*(HE***)&((XPVHV*) SvANY(hv))->xhv_array)
79072805 134#define HvFILL(hv) ((XPVHV*) SvANY(hv))->xhv_fill
463ee0b2 135#define HvMAX(hv) ((XPVHV*) SvANY(hv))->xhv_max
79072805
LW
136#define HvRITER(hv) ((XPVHV*) SvANY(hv))->xhv_riter
137#define HvEITER(hv) ((XPVHV*) SvANY(hv))->xhv_eiter
138#define HvPMROOT(hv) ((XPVHV*) SvANY(hv))->xhv_pmroot
139#define HvNAME(hv) ((XPVHV*) SvANY(hv))->xhv_name
a0d0e21e 140
8aacddc1
NIS
141/* the number of keys (including any placeholers) */
142#define XHvTOTALKEYS(xhv) ((xhv)->xhv_keys)
143
144/* The number of placeholders in the enumerated-keys hash */
205c8ad3 145#define XHvPLACEHOLDERS(xhv) ((xhv)->xhv_placeholders)
8aacddc1
NIS
146
147/* the number of keys that exist() (i.e. excluding placeholers) */
148#define XHvUSEDKEYS(xhv) (XHvTOTALKEYS(xhv) - XHvPLACEHOLDERS(xhv))
149
150/*
151 * HvKEYS gets the number of keys that actually exist(), and is provided
152 * for backwards compatibility with old XS code. The core uses HvUSEDKEYS
153 * (keys, excluding placeholdes) and HvTOTALKEYS (including placeholders)
154 */
155#define HvKEYS(hv) XHvUSEDKEYS((XPVHV*) SvANY(hv))
156#define HvUSEDKEYS(hv) XHvUSEDKEYS((XPVHV*) SvANY(hv))
157#define HvTOTALKEYS(hv) XHvTOTALKEYS((XPVHV*) SvANY(hv))
158#define HvPLACEHOLDERS(hv) XHvPLACEHOLDERS((XPVHV*) SvANY(hv))
159
160
bf6bd887
PP
161#define HvSHAREKEYS(hv) (SvFLAGS(hv) & SVphv_SHAREKEYS)
162#define HvSHAREKEYS_on(hv) (SvFLAGS(hv) |= SVphv_SHAREKEYS)
163#define HvSHAREKEYS_off(hv) (SvFLAGS(hv) &= ~SVphv_SHAREKEYS)
164
bf5b86ae
GS
165#define HvLAZYDEL(hv) (SvFLAGS(hv) & SVphv_LAZYDEL)
166#define HvLAZYDEL_on(hv) (SvFLAGS(hv) |= SVphv_LAZYDEL)
167#define HvLAZYDEL_off(hv) (SvFLAGS(hv) &= ~SVphv_LAZYDEL)
168
a0d0e21e
LW
169/* Maybe amagical: */
170/* #define HV_AMAGICmb(hv) (SvFLAGS(hv) & (SVpgv_badAM | SVpgv_AM)) */
171
172#define HV_AMAGIC(hv) (SvFLAGS(hv) & SVpgv_AM)
173#define HV_AMAGIC_on(hv) (SvFLAGS(hv) |= SVpgv_AM)
174#define HV_AMAGIC_off(hv) (SvFLAGS(hv) &= ~SVpgv_AM)
175
176/*
177#define HV_AMAGICbad(hv) (SvFLAGS(hv) & SVpgv_badAM)
178#define HV_badAMAGIC_on(hv) (SvFLAGS(hv) |= SVpgv_badAM)
179#define HV_badAMAGIC_off(hv) (SvFLAGS(hv) &= ~SVpgv_badAM)
180*/
bf6bd887
PP
181
182#define Nullhe Null(HE*)
183#define HeNEXT(he) (he)->hent_next
ff68c719
PP
184#define HeKEY_hek(he) (he)->hent_hek
185#define HeKEY(he) HEK_KEY(HeKEY_hek(he))
bbce6d69 186#define HeKEY_sv(he) (*(SV**)HeKEY(he))
ff68c719 187#define HeKLEN(he) HEK_LEN(HeKEY_hek(he))
da58a35d
JH
188#define HeKUTF8(he) HEK_UTF8(HeKEY_hek(he))
189#define HeKLEN_UTF8(he) (HeKUTF8(he) ? -HeKLEN(he) : HeKLEN(he))
bf6bd887 190#define HeVAL(he) (he)->hent_val
ff68c719 191#define HeHASH(he) HEK_HASH(HeKEY_hek(he))
1e422769
PP
192#define HePV(he,lp) ((HeKLEN(he) == HEf_SVKEY) ? \
193 SvPV(HeKEY_sv(he),lp) : \
194 (((lp = HeKLEN(he)) >= 0) ? \
195 HeKEY(he) : Nullch))
196
bbce6d69
PP
197#define HeSVKEY(he) ((HeKEY(he) && \
198 HeKLEN(he) == HEf_SVKEY) ? \
199 HeKEY_sv(he) : Nullsv)
200
201#define HeSVKEY_force(he) (HeKEY(he) ? \
202 ((HeKLEN(he) == HEf_SVKEY) ? \
203 HeKEY_sv(he) : \
79cb57f6 204 sv_2mortal(newSVpvn(HeKEY(he), \
bbce6d69 205 HeKLEN(he)))) : \
3280af22 206 &PL_sv_undef)
1e422769 207#define HeSVKEY_set(he,sv) ((HeKLEN(he) = HEf_SVKEY), (HeKEY_sv(he) = sv))
bbce6d69 208
ff68c719 209#define Nullhek Null(HEK*)
71be2cbc 210#define HEK_BASESIZE STRUCT_OFFSET(HEK, hek_key[0])
ff68c719
PP
211#define HEK_HASH(hek) (hek)->hek_hash
212#define HEK_LEN(hek) (hek)->hek_len
213#define HEK_KEY(hek) (hek)->hek_key
da58a35d 214#define HEK_UTF8(hek) (*(HEK_KEY(hek)+HEK_LEN(hek)))
d18c6117 215
5cbe4eec 216/* calculate HV array allocation */
d18c6117
GS
217#if defined(STRANGE_MALLOC) || defined(MYMALLOC)
218# define PERL_HV_ARRAY_ALLOC_BYTES(size) ((size) * sizeof(HE*))
219#else
220# define MALLOC_OVERHEAD 16
221# define PERL_HV_ARRAY_ALLOC_BYTES(size) \
222 (((size) < 64) \
223 ? (size) * sizeof(HE*) \
224 : (size) * sizeof(HE*) * 2 - MALLOC_OVERHEAD)
225#endif
37d85e3a
JH
226
227/* available as a function in hv.c */
228#define Perl_sharepvn(sv, len, hash) HEK_KEY(share_hek(sv, len, hash))
229#define sharepvn(sv, len, hash) Perl_sharepvn(sv, len, hash)