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

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