From 289d3c6afee2ee5aaa9c3c2e0498d35fffce0173 Mon Sep 17 00:00:00 2001
From: Nicholas Clark <nick@ccl4.org>
Date: Thu, 3 Jan 2008 14:23:17 +0000
Subject: [PATCH] Add HeUTF8() to complement HePV() and then immediately
 suggest that newSVhek(HeKEY_hek(he) is probably what you wanted all along.

p4raw-id: //depot/perl@32812
---
 hv.h            | 16 +++++++++++++++-
 pod/perlapi.pod | 20 +++++++++++++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/hv.h b/hv.h
index 8d4088e..3be32e6 100644
--- a/hv.h
+++ b/hv.h
@@ -198,7 +198,18 @@ variable C<PL_na>, 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<strlen()> or similar is not a good way to find
 the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document.
+described elsewhere in this document. See also C<HeUTF8>.
+
+If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
+new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
+efficient.
+
+=for apidoc Am|char*|HeUTF8|HE* he|STRLEN len
+Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
+doing any necessary dereferencing of possibly C<SV*> keys.  The value returned
+will be 0 or non-0, not necesarily 1 (or even a value with any low bits set),
+so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
+typedef for C<char>.
 
 =for apidoc Am|SV*|HeSVKEY|HE* he
 Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
@@ -305,6 +316,9 @@ C<SV*>.
 #define HePV(he,lp)		((HeKLEN(he) == HEf_SVKEY) ?		\
 				 SvPV(HeKEY_sv(he),lp) :		\
 				 ((lp = HeKLEN(he)), HeKEY(he)))
+#define HeUTF8(he)		((HeKLEN(he) == HEf_SVKEY) ?		\
+				 SvUTF8(HeKEY_sv(he)) :			\
+				 (U32)HeKUTF8(he))
 
 #define HeSVKEY(he)		((HeKEY(he) && 				\
 				  HeKLEN(he) == HEf_SVKEY) ?		\
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index b7cb7b3..8546d4f 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -1512,7 +1512,11 @@ variable C<PL_na>, 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<strlen()> or similar is not a good way to find
 the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document.
+described elsewhere in this document. See also C<HeUTF8>.
+
+If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
+new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
+efficient.
 
 	char*	HePV(HE* he, STRLEN len)
 
@@ -1553,6 +1557,20 @@ C<SV*>.
 =for hackers
 Found in file hv.h
 
+=item HeUTF8
+X<HeUTF8>
+
+Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
+doing any necessary dereferencing of possibly C<SV*> keys.  The value returned
+will be 0 or non-0, not necesarily 1 (or even a value with any low bits set),
+so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
+typedef for C<char>.
+
+	char*	HeUTF8(HE* he, STRLEN len)
+
+=for hackers
+Found in file hv.h
+
 =item HeVAL
 X<HeVAL>
 
-- 
1.8.3.1