/*    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 */#define PERL_HASH(hash,str,len) \     STMT_START	{ \	register const char *s_PeRlHaSh = str; \	register I32 i_PeRlHaSh = len; \	register U32 hash_PeRlHaSh = 0; \	while (i_PeRlHaSh--) \	    hash_PeRlHaSh = hash_PeRlHaSh * 33 + *s_PeRlHaSh++; \	(hash) = hash_PeRlHaSh + (hash_PeRlHaSh>>5); \    } STMT_END/*=for apidoc AmU||HEf_SVKEYThis flag, used in the length slot of hash entries and magic structures,specifies the structure contains a C<SV*> pointer where a C<char*> pointeris to be expected. (For information only--not to be used).=for apidoc AmU||NullhvNull HV pointer.=for apidoc Am|char*|HvNAME|HV* stashReturns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.=for apidoc Am|void*|HeKEY|HE* heReturns the actual pointer stored in the key slot of the hash entry. Thepointer may be either C<char*> or C<SV*>, depending on the value ofC<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros areusually preferable for finding the value of a key.=for apidoc Am|STRLEN|HeKLEN|HE* heIf this is negative, and amounts to C<HEf_SVKEY>, it indicates the entryholds an C<SV*> key.  Otherwise, holds the actual length of the key.  Canbe assigned to. The C<HePV()> macro is usually preferable for finding keylengths.=for apidoc Am|SV*|HeVAL|HE* heReturns the value slot (type C<SV*>) stored in the hash entry.=for apidoc Am|U32|HeHASH|HE* heReturns the computed hash stored in the hash entry.=for apidoc Am|char*|HePV|HE* he|STRLEN lenReturns the key slot of the hash entry as a C<char*> value, doing anynecessary dereferencing of possibly C<SV*> keys.  The length of the stringis placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you donot care about what the length of the key is, you may use the globalvariable C<PL_na>, though this is rather less efficient than using a localvariable.  Remember though, that hash keys in perl are free to containembedded nulls, so using C<strlen()> or similar is not a good way to findthe length of hash keys. This is very similar to the C<SvPV()> macrodescribed elsewhere in this document.=for apidoc Am|SV*|HeSVKEY|HE* heReturns the key as an C<SV*>, or C<Nullsv> if the hash entry does notcontain an C<SV*> key.=for apidoc Am|SV*|HeSVKEY_force|HE* heReturns the key as an C<SV*>.  Will create and return a temporary mortalC<SV*> if the hash entry contains only a C<char*> key.=for apidoc Am|SV*|HeSVKEY_set|HE* he|SV* svSets the key to a given C<SV*>, taking care to set the appropriate flags toindicate the presence of an C<SV*> key, and returns the sameC<SV*>.=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