From: Karl Williamson <public@khwilliamson.com>
Date: Sun, 15 Jul 2012 23:02:19 +0000 (-0600)
Subject: perlapi: Clarify hv_fetch() docs
X-Git-Tag: v5.17.2~13
X-Git-Url: https://perl5.git.perl.org/perl5.git/commitdiff_plain/43d3b06a68c324615c5d1909e183687a40b0bb19?ds=sidebyside

perlapi: Clarify hv_fetch() docs

I was confused by the earlier documentation.  Thanks to Leon Timmermans
for clarifying, and to Vicent Pitt for most of the wording
---

diff --git a/hv.c b/hv.c
index ac826f1..c4cf736 100644
--- a/hv.c
+++ b/hv.c
@@ -277,7 +277,10 @@ negative the key is assumed to be in UTF-8-encoded Unicode.
 Returns the SV which corresponds to the specified key in the hash.
 The absolute value of C<klen> is the length of the key.  If C<klen> is
 negative the key is assumed to be in UTF-8-encoded Unicode.  If
-C<lval> is set then the fetch will be part of a store.  Check that the
+C<lval> is set then the fetch will be part of a store.  This means that if
+there is no value in the hash associated with the given key, then one is
+created and a pointer to it is returned.  The C<SV*> it points to can be
+assigned to.  But always check that the
 return value is non-null before dereferencing it to an C<SV*>.
 
 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more