X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/551f9d97a74adb55882f5ce5672c5682fd80c0f6..02c53a431e8c99d69a002753de31af1dc2d9f30e:/hv.h

diff --git a/hv.h b/hv.h
index 55dd475..ebb81d1 100644
--- a/hv.h
+++ b/hv.h
@@ -50,7 +50,6 @@ struct hek {
      * dont work on aligned platforms like HPUX
      * Also beware, the last byte of the hek_key buffer is a
      * hidden flags byte about the key. */
-     */
      char       hek_key[1];        /* variable-length hash key */
     /* the hash-key is \0-terminated */
     /* after the \0 there is a byte for flags, such as whether the key
@@ -141,22 +140,18 @@ struct xpvhv {
 };
 
 /*
-=head1 Hash Manipulation Functions
+=for apidoc_section HV Handling
 
-=for apidoc AmU||HEf_SVKEY
+=for apidoc AmnU||HEf_SVKEY
 This flag, used in the length slot of hash entries and magic structures,
 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
 is to be expected.  (For information only--not to be used).
 
-=head1 Handy Values
-
-=for apidoc AmU||Nullhv
+=for apidoc ADmnU||Nullhv
 Null HV pointer.
 
 (deprecated - use C<(HV *)NULL> instead)
 
-=head1 Hash Manipulation Functions
-
 =for apidoc Am|char*|HvNAME|HV* stash
 Returns the package name of a stash, or C<NULL> if C<stash> isn't a stash.
 See C<L</SvSTASH>>, C<L</CvSTASH>>.
@@ -164,6 +159,10 @@ See C<L</SvSTASH>>, C<L</CvSTASH>>.
 =for apidoc Am|STRLEN|HvNAMELEN|HV *stash
 Returns the length of the stash's name.
 
+Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
+=for apidoc Cmh|char*|HvNAME_get|HV* stash
+=for apidoc Amh|I32|HvNAMELEN_get|HV* stash
+
 =for apidoc Am|unsigned char|HvNAMEUTF8|HV *stash
 Returns true if the name is in UTF-8 encoding.
 
@@ -264,6 +263,16 @@ C<SV*>.
 #  define Nullhv Null(HV*)
 #endif
 #define HvARRAY(hv)	((hv)->sv_u.svu_hash)
+
+/*
+
+=for apidoc Am|STRLEN|HvFILL|HV *const hv
+
+See L</hv_fill>.
+
+=cut
+
+*/
 #define HvFILL(hv)	Perl_hv_fill(aTHX_ MUTABLE_HV(hv))
 #define HvMAX(hv)	((XPVHV*)  SvANY(hv))->xhv_max
 /* This quite intentionally does no flag checking first. That's your
@@ -326,7 +335,7 @@ C<SV*>.
    ((SvOOK(hv) && HvAUX(hv)->xhv_name_u.xhvnameu_name && HvAUX(hv)->xhv_name_count != -1) \
 				 ? HEK_UTF8(HvENAME_HEK_NN(hv)) : 0)
 
-/* the number of keys (including any placeholders) */
+/* the number of keys (including any placeholders) - NOT PART OF THE API */
 #define XHvTOTALKEYS(xhv)	((xhv)->xhv_keys)
 
 /*
@@ -462,8 +471,7 @@ C<SV*>.
 		      (val), (hash)))
 
 #define hv_exists_ent(hv, keysv, hash)					\
-    (hv_common((hv), (keysv), NULL, 0, 0, HV_FETCH_ISEXISTS, 0, (hash))	\
-     ? TRUE : FALSE)
+    cBOOL(hv_common((hv), (keysv), NULL, 0, 0, HV_FETCH_ISEXISTS, 0, (hash)))
 #define hv_fetch_ent(hv, keysv, lval, hash)				\
     ((HE *) hv_common((hv), (keysv), NULL, 0, 0,			\
 		      ((lval) ? HV_FETCH_LVALUE : 0), NULL, (hash)))
@@ -484,8 +492,7 @@ C<SV*>.
 
 
 #define hv_exists(hv, key, klen)					\
-    (hv_common_key_len((hv), (key), (klen), HV_FETCH_ISEXISTS, NULL, 0) \
-     ? TRUE : FALSE)
+    cBOOL(hv_common_key_len((hv), (key), (klen), HV_FETCH_ISEXISTS, NULL, 0))
 
 #define hv_fetch(hv, key, klen, lval)					\
     ((SV**) hv_common_key_len((hv), (key), (klen), (lval)		\
@@ -568,9 +575,9 @@ struct refcounted_he {
 };
 
 /*
-=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|const char *key|U32 flags
+=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|"key"|U32 flags
 
-Like L</refcounted_he_fetch_pvn>, but takes a C<NUL>-terminated literal string
+Like L</refcounted_he_fetch_pvn>, but takes a literal string
 instead of a string/length pair, and no precomputed hash.
 
 =cut
@@ -580,9 +587,9 @@ instead of a string/length pair, and no precomputed hash.
     Perl_refcounted_he_fetch_pvn(aTHX_ chain, STR_WITH_LEN(key), 0, flags)
 
 /*
-=for apidoc m|struct refcounted_he *|refcounted_he_new_pvs|struct refcounted_he *parent|const char *key|SV *value|U32 flags
+=for apidoc m|struct refcounted_he *|refcounted_he_new_pvs|struct refcounted_he *parent|"key"|SV *value|U32 flags
 
-Like L</refcounted_he_new_pvn>, but takes a C<NUL>-terminated literal string
+Like L</refcounted_he_new_pvn>, but takes a literal string
 instead of a string/length pair, and no precomputed hash.
 
 =cut