This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Clarify entry for hv_store()
authorKarl Williamson <khw@cpan.org>
Thu, 7 Mar 2019 22:29:28 +0000 (15:29 -0700)
committerKarl Williamson <khw@cpan.org>
Tue, 12 Mar 2019 16:01:30 +0000 (10:01 -0600)
hv.c

diff --git a/hv.c b/hv.c
index fc90a51..1371b2f 100644 (file)
--- a/hv.c
+++ b/hv.c
@@ -260,7 +260,9 @@ if all your code does is create SVs then store them in a hash, C<hv_store>
 will own the only reference to the new SV, and your code doesn't need to do
 anything further to tidy up.  Note that C<hv_store_ent> only reads the C<key>;
 unlike C<val> it does not take ownership of it, so maintaining the correct
 will own the only reference to the new SV, and your code doesn't need to do
 anything further to tidy up.  Note that C<hv_store_ent> only reads the C<key>;
 unlike C<val> it does not take ownership of it, so maintaining the correct
-reference count on C<key> is entirely the caller's responsibility.  C<hv_store>
+reference count on C<key> is entirely the caller's responsibility.  The reason
+it does not take ownership, is that C<key> is not used after this function
+returns, and so can be freed immediately.  C<hv_store>
 is not implemented as a call to C<hv_store_ent>, and does not create a temporary
 SV for the key, so if your key data is not already in SV form then use
 C<hv_store> in preference to C<hv_store_ent>.
 is not implemented as a call to C<hv_store_ent>, and does not create a temporary
 SV for the key, so if your key data is not already in SV form then use
 C<hv_store> in preference to C<hv_store_ent>.