X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/954c1994944eafa74aaac1bab94e820b6e447da9..14e6b36c1ccc1a5d5b6d44274725d8f63769d3a3:/hv.h diff --git a/hv.h b/hv.h index f052258..3d51075 100644 --- a/hv.h +++ b/hv.h @@ -1,27 +1,33 @@ /* hv.h * - * Copyright (c) 1991-1999, Larry Wall + * Copyright (c) 1991-2002, 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; - HEK *hent_hek; - SV *hent_val; + 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; - I32 hek_len; - char hek_key[1]; + U32 hek_hash; /* hash of key */ + I32 hek_len; /* length of hash key */ + char hek_key[1]; /* variable-length hash key */ + /* the hash-key is \0-terminated */ + /* after the \0 there is a byte telling whether the key is UTF8 */ }; +/* hash structure: */ /* This structure must match the beginning of struct xpvmg in sv.h. */ struct xpvhv { char * xhv_array; /* pointer to malloced string */ @@ -29,6 +35,7 @@ struct xpvhv { 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 */ +#define xhv_placeholders xnv_nv MAGIC* xmg_magic; /* magic for scalar array */ HV* xmg_stash; /* class package */ @@ -38,25 +45,40 @@ struct xpvhv { 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) */ #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); \ + 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 /* +=head1 Hash Manipulation Functions + =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 +specifies the structure contains an C pointer where a C pointer is to be expected. (For information only--not to be used). +=head1 Handy Values + =for apidoc AmU||Nullhv Null HV pointer. +=head1 Hash Manipulation Functions + =for apidoc Am|char*|HvNAME|HV* stash Returns the package name of a stash. See C, C. @@ -106,23 +128,45 @@ C. */ /* 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 HEf_SVKEY -2 /* hent_key is an SV* */ #define Nullhv Null(HV*) -#define HvARRAY(hv) ((HE**)((XPVHV*) SvANY(hv))->xhv_array) +#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 +/* the number of keys (including any placeholers) */ +#define XHvTOTALKEYS(xhv) ((xhv)->xhv_keys) + +/* The number of placeholders in the enumerated-keys hash */ +#define XHvPLACEHOLDERS(xhv) ((xhv)->xhv_placeholders) + +/* the number of keys that exist() (i.e. excluding placeholders) */ +#define XHvUSEDKEYS(xhv) (XHvTOTALKEYS(xhv) - (IV)XHvPLACEHOLDERS(xhv)) + +/* + * HvKEYS gets the number of keys that actually exist(), and is provided + * for backwards compatibility with old XS code. The core uses HvUSEDKEYS + * (keys, excluding placeholdes) and HvTOTALKEYS (including placeholders) + */ +#define HvKEYS(hv) XHvUSEDKEYS((XPVHV*) SvANY(hv)) +#define HvUSEDKEYS(hv) XHvUSEDKEYS((XPVHV*) SvANY(hv)) +#define HvTOTALKEYS(hv) XHvTOTALKEYS((XPVHV*) SvANY(hv)) +#define HvPLACEHOLDERS(hv) XHvPLACEHOLDERS((XPVHV*) SvANY(hv)) + #define HvSHAREKEYS(hv) (SvFLAGS(hv) & SVphv_SHAREKEYS) #define HvSHAREKEYS_on(hv) (SvFLAGS(hv) |= SVphv_SHAREKEYS) #define HvSHAREKEYS_off(hv) (SvFLAGS(hv) &= ~SVphv_SHAREKEYS) +#define HvUTF8KEYS(hv) (SvFLAGS(hv) & SVphv_UTF8KEYS) +#define HvUTF8KEYS_on(hv) (SvFLAGS(hv) |= SVphv_UTF8KEYS) +#define HvUTF8KEYS_off(hv) (SvFLAGS(hv) &= ~SVphv_UTF8KEYS) + #define HvLAZYDEL(hv) (SvFLAGS(hv) & SVphv_LAZYDEL) #define HvLAZYDEL_on(hv) (SvFLAGS(hv) |= SVphv_LAZYDEL) #define HvLAZYDEL_off(hv) (SvFLAGS(hv) &= ~SVphv_LAZYDEL) @@ -146,6 +190,8 @@ C. #define HeKEY(he) HEK_KEY(HeKEY_hek(he)) #define HeKEY_sv(he) (*(SV**)HeKEY(he)) #define HeKLEN(he) HEK_LEN(HeKEY_hek(he)) +#define HeKUTF8(he) HEK_UTF8(HeKEY_hek(he)) +#define HeKLEN_UTF8(he) (HeKUTF8(he) ? -HeKLEN(he) : HeKLEN(he)) #define HeVAL(he) (he)->hent_val #define HeHASH(he) HEK_HASH(HeKEY_hek(he)) #define HePV(he,lp) ((HeKLEN(he) == HEf_SVKEY) ? \ @@ -170,7 +216,9 @@ C. #define HEK_HASH(hek) (hek)->hek_hash #define HEK_LEN(hek) (hek)->hek_len #define HEK_KEY(hek) (hek)->hek_key +#define HEK_UTF8(hek) (*(HEK_KEY(hek)+HEK_LEN(hek)+1)) +/* calculate HV array allocation */ #if defined(STRANGE_MALLOC) || defined(MYMALLOC) # define PERL_HV_ARRAY_ALLOC_BYTES(size) ((size) * sizeof(HE*)) #else @@ -180,3 +228,7 @@ C. ? (size) * sizeof(HE*) \ : (size) * sizeof(HE*) * 2 - MALLOC_OVERHEAD) #endif + +/* available as a function in hv.c */ +#define Perl_sharepvn(sv, len, hash) HEK_KEY(share_hek(sv, len, hash)) +#define sharepvn(sv, len, hash) Perl_sharepvn(sv, len, hash)