source: trunk/third/perl/hv.h @ 17035

Revision 17035, 6.6 KB checked in by zacheiss, 22 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r17034, which included commits to RCS files with non-trunk default branches.
Line 
1/*    hv.h
2 *
3 *    Copyright (c) 1991-2001, Larry Wall
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 *
8 */
9
10/* typedefs to eliminate some typing */
11typedef struct he HE;
12typedef struct hek HEK;
13
14/* entry in hash value chain */
15struct he {
16    HE          *hent_next;     /* next entry in chain */
17    HEK         *hent_hek;      /* hash key */
18    SV          *hent_val;      /* scalar value that was hashed */
19};
20
21/* hash key -- defined separately for use as shared pointer */
22struct hek {
23    U32         hek_hash;       /* hash of key */
24    I32         hek_len;        /* length of hash key */
25    char        hek_key[1];     /* variable-length hash key */
26};
27
28/* hash structure: */
29/* This structure must match the beginning of struct xpvmg in sv.h. */
30struct xpvhv {
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 */
34    IV          xhv_keys;       /* how many elements in the array */
35    NV          xnv_nv;         /* numeric value, if any */
36    MAGIC*      xmg_magic;      /* magic for scalar array */
37    HV*         xmg_stash;      /* class package */
38
39    I32         xhv_riter;      /* current root of iterator */
40    HE          *xhv_eiter;     /* current entry of iterator */
41    PMOP        *xhv_pmroot;    /* list of pm's for this package */
42    char        *xhv_name;      /* name, if a symbol table */
43};
44
45/* hash a key */
46#define PERL_HASH(hash,str,len) \
47     STMT_START { \
48        register const char *s_PeRlHaSh = str; \
49        register I32 i_PeRlHaSh = len; \
50        register U32 hash_PeRlHaSh = 0; \
51        while (i_PeRlHaSh--) \
52            hash_PeRlHaSh = hash_PeRlHaSh * 33 + *s_PeRlHaSh++; \
53        (hash) = hash_PeRlHaSh + (hash_PeRlHaSh>>5); \
54    } STMT_END
55
56/*
57=for apidoc AmU||HEf_SVKEY
58This flag, used in the length slot of hash entries and magic structures,
59specifies the structure contains a C<SV*> pointer where a C<char*> pointer
60is to be expected. (For information only--not to be used).
61
62=for apidoc AmU||Nullhv
63Null HV pointer.
64
65=for apidoc Am|char*|HvNAME|HV* stash
66Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
67
68=for apidoc Am|void*|HeKEY|HE* he
69Returns the actual pointer stored in the key slot of the hash entry. The
70pointer may be either C<char*> or C<SV*>, depending on the value of
71C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
72usually preferable for finding the value of a key.
73
74=for apidoc Am|STRLEN|HeKLEN|HE* he
75If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
76holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
77be assigned to. The C<HePV()> macro is usually preferable for finding key
78lengths.
79
80=for apidoc Am|SV*|HeVAL|HE* he
81Returns the value slot (type C<SV*>) stored in the hash entry.
82
83=for apidoc Am|U32|HeHASH|HE* he
84Returns the computed hash stored in the hash entry.
85
86=for apidoc Am|char*|HePV|HE* he|STRLEN len
87Returns the key slot of the hash entry as a C<char*> value, doing any
88necessary dereferencing of possibly C<SV*> keys.  The length of the string
89is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
90not care about what the length of the key is, you may use the global
91variable C<PL_na>, though this is rather less efficient than using a local
92variable.  Remember though, that hash keys in perl are free to contain
93embedded nulls, so using C<strlen()> or similar is not a good way to find
94the length of hash keys. This is very similar to the C<SvPV()> macro
95described elsewhere in this document.
96
97=for apidoc Am|SV*|HeSVKEY|HE* he
98Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
99contain an C<SV*> key.
100
101=for apidoc Am|SV*|HeSVKEY_force|HE* he
102Returns the key as an C<SV*>.  Will create and return a temporary mortal
103C<SV*> if the hash entry contains only a C<char*> key.
104
105=for apidoc Am|SV*|HeSVKEY_set|HE* he|SV* sv
106Sets the key to a given C<SV*>, taking care to set the appropriate flags to
107indicate the presence of an C<SV*> key, and returns the same
108C<SV*>.
109
110=cut
111*/
112
113/* these hash entry flags ride on hent_klen (for use only in magic/tied HVs) */
114#define HEf_SVKEY       -2      /* hent_key is a SV* */
115
116
117#define Nullhv Null(HV*)
118#define HvARRAY(hv)     ((HE**)((XPVHV*)  SvANY(hv))->xhv_array)
119#define HvFILL(hv)      ((XPVHV*)  SvANY(hv))->xhv_fill
120#define HvMAX(hv)       ((XPVHV*)  SvANY(hv))->xhv_max
121#define HvKEYS(hv)      ((XPVHV*)  SvANY(hv))->xhv_keys
122#define HvRITER(hv)     ((XPVHV*)  SvANY(hv))->xhv_riter
123#define HvEITER(hv)     ((XPVHV*)  SvANY(hv))->xhv_eiter
124#define HvPMROOT(hv)    ((XPVHV*)  SvANY(hv))->xhv_pmroot
125#define HvNAME(hv)      ((XPVHV*)  SvANY(hv))->xhv_name
126
127#define HvSHAREKEYS(hv)         (SvFLAGS(hv) & SVphv_SHAREKEYS)
128#define HvSHAREKEYS_on(hv)      (SvFLAGS(hv) |= SVphv_SHAREKEYS)
129#define HvSHAREKEYS_off(hv)     (SvFLAGS(hv) &= ~SVphv_SHAREKEYS)
130
131#define HvLAZYDEL(hv)           (SvFLAGS(hv) & SVphv_LAZYDEL)
132#define HvLAZYDEL_on(hv)        (SvFLAGS(hv) |= SVphv_LAZYDEL)
133#define HvLAZYDEL_off(hv)       (SvFLAGS(hv) &= ~SVphv_LAZYDEL)
134
135/* Maybe amagical: */
136/* #define HV_AMAGICmb(hv)      (SvFLAGS(hv) & (SVpgv_badAM | SVpgv_AM)) */
137
138#define HV_AMAGIC(hv)        (SvFLAGS(hv) &   SVpgv_AM)
139#define HV_AMAGIC_on(hv)     (SvFLAGS(hv) |=  SVpgv_AM)
140#define HV_AMAGIC_off(hv)    (SvFLAGS(hv) &= ~SVpgv_AM)
141
142/*
143#define HV_AMAGICbad(hv)     (SvFLAGS(hv) & SVpgv_badAM)
144#define HV_badAMAGIC_on(hv)  (SvFLAGS(hv) |= SVpgv_badAM)
145#define HV_badAMAGIC_off(hv) (SvFLAGS(hv) &= ~SVpgv_badAM)
146*/
147
148#define Nullhe Null(HE*)
149#define HeNEXT(he)              (he)->hent_next
150#define HeKEY_hek(he)           (he)->hent_hek
151#define HeKEY(he)               HEK_KEY(HeKEY_hek(he))
152#define HeKEY_sv(he)            (*(SV**)HeKEY(he))
153#define HeKLEN(he)              HEK_LEN(HeKEY_hek(he))
154#define HeVAL(he)               (he)->hent_val
155#define HeHASH(he)              HEK_HASH(HeKEY_hek(he))
156#define HePV(he,lp)             ((HeKLEN(he) == HEf_SVKEY) ?            \
157                                 SvPV(HeKEY_sv(he),lp) :                \
158                                 (((lp = HeKLEN(he)) >= 0) ?            \
159                                  HeKEY(he) : Nullch))
160
161#define HeSVKEY(he)             ((HeKEY(he) &&                          \
162                                  HeKLEN(he) == HEf_SVKEY) ?            \
163                                 HeKEY_sv(he) : Nullsv)
164
165#define HeSVKEY_force(he)       (HeKEY(he) ?                            \
166                                 ((HeKLEN(he) == HEf_SVKEY) ?           \
167                                  HeKEY_sv(he) :                        \
168                                  sv_2mortal(newSVpvn(HeKEY(he),        \
169                                                     HeKLEN(he)))) :    \
170                                 &PL_sv_undef)
171#define HeSVKEY_set(he,sv)      ((HeKLEN(he) = HEf_SVKEY), (HeKEY_sv(he) = sv))
172
173#define Nullhek Null(HEK*)
174#define HEK_BASESIZE            STRUCT_OFFSET(HEK, hek_key[0])
175#define HEK_HASH(hek)           (hek)->hek_hash
176#define HEK_LEN(hek)            (hek)->hek_len
177#define HEK_KEY(hek)            (hek)->hek_key
178
179/* calculate HV array allocation */
180#if defined(STRANGE_MALLOC) || defined(MYMALLOC)
181#  define PERL_HV_ARRAY_ALLOC_BYTES(size) ((size) * sizeof(HE*))
182#else
183#  define MALLOC_OVERHEAD 16
184#  define PERL_HV_ARRAY_ALLOC_BYTES(size) \
185                        (((size) < 64)                                  \
186                         ? (size) * sizeof(HE*)                         \
187                         : (size) * sizeof(HE*) * 2 - MALLOC_OVERHEAD)
188#endif
Note: See TracBrowser for help on using the repository browser.