/* hv.h * * Copyright (c) 1991-2001, Larry Wall * * You may distribute under the terms of either the GNU General Public * License or the Artistic License, as specified in the README file. * */ /* typedefs to eliminate some typing */ typedef struct he HE; typedef struct hek HEK; /* entry in hash value chain */ struct he { HE *hent_next; /* next entry in chain */ HEK *hent_hek; /* hash key */ SV *hent_val; /* scalar value that was hashed */ }; /* hash key -- defined separately for use as shared pointer */ struct hek { U32 hek_hash; /* hash of key */ I32 hek_len; /* length of hash key */ char hek_key[1]; /* variable-length hash key */ }; /* hash structure: */ /* This structure must match the beginning of struct xpvmg in sv.h. */ struct xpvhv { char * xhv_array; /* pointer to malloced string */ STRLEN xhv_fill; /* how full xhv_array currently is */ STRLEN xhv_max; /* subscript of last element of xhv_array */ IV xhv_keys; /* how many elements in the array */ NV xnv_nv; /* numeric value, if any */ MAGIC* xmg_magic; /* magic for scalar array */ HV* xmg_stash; /* class package */ I32 xhv_riter; /* current root of iterator */ HE *xhv_eiter; /* current entry of iterator */ PMOP *xhv_pmroot; /* list of pm's for this package */ char *xhv_name; /* name, if a symbol table */ }; /* hash a key */ /* FYI: This is the "One-at-a-Time" algorithm by Bob Jenkins * from requirements by Colin Plumb. * (http://burtleburtle.net/bob/hash/doobs.html) */ /* The use of a temporary pointer and the casting games * is needed to serve the dual purposes of * (a) the hashed data being interpreted as "unsigned char" (new since 5.8, * a "char" can be either signed or signed, depending on the compiler) * (b) catering for old code that uses a "char" * * The "hash seed" feature was added in Perl 5.8.1 to perturb the results * to avoid "algorithmic complexity attacks". * * If USE_HASH_SEED is defined, hash randomisation is done by default * If USE_HASH_SEED_EXPLICIT is defined, hash randomisation is done * only if the environment variable PERL_HASH_SEED is set. * For maximal control, one can define PERL_HASH_SEED. * (see also perl.c:perl_parse()). */ #ifndef PERL_HASH_SEED # if defined(USE_HASH_SEED) || defined(USE_HASH_SEED_EXPLICIT) # define PERL_HASH_SEED PL_hash_seed # else # define PERL_HASH_SEED 0 # endif #endif #define PERL_HASH(hash,str,len) \ STMT_START { \ register const char *s_PeRlHaSh_tmp = str; \ register const unsigned char *s_PeRlHaSh = (const unsigned char *)s_PeRlHaSh_tmp; \ register I32 i_PeRlHaSh = len; \ register U32 hash_PeRlHaSh = PERL_HASH_SEED; \ while (i_PeRlHaSh--) { \ hash_PeRlHaSh += *s_PeRlHaSh++; \ hash_PeRlHaSh += (hash_PeRlHaSh << 10); \ hash_PeRlHaSh ^= (hash_PeRlHaSh >> 6); \ } \ hash_PeRlHaSh += (hash_PeRlHaSh << 3); \ hash_PeRlHaSh ^= (hash_PeRlHaSh >> 11); \ (hash) = (hash_PeRlHaSh + (hash_PeRlHaSh << 15)); \ } STMT_END /* =for apidoc AmU||HEf_SVKEY This flag, used in the length slot of hash entries and magic structures, specifies the structure contains a C pointer where a C pointer is to be expected. (For information only--not to be used). =for apidoc AmU||Nullhv Null HV pointer. =for apidoc Am|char*|HvNAME|HV* stash Returns the package name of a stash. See C, C. =for apidoc Am|void*|HeKEY|HE* he Returns the actual pointer stored in the key slot of the hash entry. The pointer may be either C or C, depending on the value of C. Can be assigned to. The C or C macros are usually preferable for finding the value of a key. =for apidoc Am|STRLEN|HeKLEN|HE* he If this is negative, and amounts to C, it indicates the entry holds an C key. Otherwise, holds the actual length of the key. Can be assigned to. The C macro is usually preferable for finding key lengths. =for apidoc Am|SV*|HeVAL|HE* he Returns the value slot (type C) stored in the hash entry. =for apidoc Am|U32|HeHASH|HE* he Returns the computed hash stored in the hash entry. =for apidoc Am|char*|HePV|HE* he|STRLEN len Returns the key slot of the hash entry as a C value, doing any necessary dereferencing of possibly C keys. The length of the string is placed in C (this is a macro, so do I use C<&len>). If you do not care about what the length of the key is, you may use the global variable C, though this is rather less efficient than using a local variable. Remember though, that hash keys in perl are free to contain embedded nulls, so using C or similar is not a good way to find the length of hash keys. This is very similar to the C macro described elsewhere in this document. =for apidoc Am|SV*|HeSVKEY|HE* he Returns the key as an C, or C if the hash entry does not contain an C key. =for apidoc Am|SV*|HeSVKEY_force|HE* he Returns the key as an C. Will create and return a temporary mortal C if the hash entry contains only a C key. =for apidoc Am|SV*|HeSVKEY_set|HE* he|SV* sv Sets the key to a given C, taking care to set the appropriate flags to indicate the presence of an C key, and returns the same C. =cut */ /* these hash entry flags ride on hent_klen (for use only in magic/tied HVs) */ #define HEf_SVKEY -2 /* hent_key is a SV* */ #define Nullhv Null(HV*) #define HvARRAY(hv) ((HE**)((XPVHV*) SvANY(hv))->xhv_array) #define HvFILL(hv) ((XPVHV*) SvANY(hv))->xhv_fill #define HvMAX(hv) ((XPVHV*) SvANY(hv))->xhv_max #define HvKEYS(hv) ((XPVHV*) SvANY(hv))->xhv_keys #define HvRITER(hv) ((XPVHV*) SvANY(hv))->xhv_riter #define HvEITER(hv) ((XPVHV*) SvANY(hv))->xhv_eiter #define HvPMROOT(hv) ((XPVHV*) SvANY(hv))->xhv_pmroot #define HvNAME(hv) ((XPVHV*) SvANY(hv))->xhv_name #define HvSHAREKEYS(hv) (SvFLAGS(hv) & SVphv_SHAREKEYS) #define HvSHAREKEYS_on(hv) (SvFLAGS(hv) |= SVphv_SHAREKEYS) #define HvSHAREKEYS_off(hv) (SvFLAGS(hv) &= ~SVphv_SHAREKEYS) #define HvLAZYDEL(hv) (SvFLAGS(hv) & SVphv_LAZYDEL) #define HvLAZYDEL_on(hv) (SvFLAGS(hv) |= SVphv_LAZYDEL) #define HvLAZYDEL_off(hv) (SvFLAGS(hv) &= ~SVphv_LAZYDEL) /* Maybe amagical: */ /* #define HV_AMAGICmb(hv) (SvFLAGS(hv) & (SVpgv_badAM | SVpgv_AM)) */ #define HV_AMAGIC(hv) (SvFLAGS(hv) & SVpgv_AM) #define HV_AMAGIC_on(hv) (SvFLAGS(hv) |= SVpgv_AM) #define HV_AMAGIC_off(hv) (SvFLAGS(hv) &= ~SVpgv_AM) /* #define HV_AMAGICbad(hv) (SvFLAGS(hv) & SVpgv_badAM) #define HV_badAMAGIC_on(hv) (SvFLAGS(hv) |= SVpgv_badAM) #define HV_badAMAGIC_off(hv) (SvFLAGS(hv) &= ~SVpgv_badAM) */ #define Nullhe Null(HE*) #define HeNEXT(he) (he)->hent_next #define HeKEY_hek(he) (he)->hent_hek #define HeKEY(he) HEK_KEY(HeKEY_hek(he)) #define HeKEY_sv(he) (*(SV**)HeKEY(he)) #define HeKLEN(he) HEK_LEN(HeKEY_hek(he)) #define HeVAL(he) (he)->hent_val #define HeHASH(he) HEK_HASH(HeKEY_hek(he)) #define HePV(he,lp) ((HeKLEN(he) == HEf_SVKEY) ? \ SvPV(HeKEY_sv(he),lp) : \ (((lp = HeKLEN(he)) >= 0) ? \ HeKEY(he) : Nullch)) #define HeSVKEY(he) ((HeKEY(he) && \ HeKLEN(he) == HEf_SVKEY) ? \ HeKEY_sv(he) : Nullsv) #define HeSVKEY_force(he) (HeKEY(he) ? \ ((HeKLEN(he) == HEf_SVKEY) ? \ HeKEY_sv(he) : \ sv_2mortal(newSVpvn(HeKEY(he), \ HeKLEN(he)))) : \ &PL_sv_undef) #define HeSVKEY_set(he,sv) ((HeKLEN(he) = HEf_SVKEY), (HeKEY_sv(he) = sv)) #define Nullhek Null(HEK*) #define HEK_BASESIZE STRUCT_OFFSET(HEK, hek_key[0]) #define HEK_HASH(hek) (hek)->hek_hash #define HEK_LEN(hek) (hek)->hek_len #define HEK_KEY(hek) (hek)->hek_key /* calculate HV array allocation */ #if defined(STRANGE_MALLOC) || defined(MYMALLOC) # define PERL_HV_ARRAY_ALLOC_BYTES(size) ((size) * sizeof(HE*)) #else # define MALLOC_OVERHEAD 16 # define PERL_HV_ARRAY_ALLOC_BYTES(size) \ (((size) < 64) \ ? (size) * sizeof(HE*) \ : (size) * sizeof(HE*) * 2 - MALLOC_OVERHEAD) #endif