Change 18463 by rgs@rgs-home on 2003/01/08 21:27:49 Subject: [DOCPATCH] hv_store and hv_store_ent From: Nicholas Clark <[EMAIL PROTECTED]> Date: Wed, 1 Jan 2003 18:17:59 +0000 Message-ID: <[EMAIL PROTECTED]> (Integrated from change #18399 from maint-5.8)
Affected files ... ... //depot/perl/hv.c#120 integrate Differences ... ==== //depot/perl/hv.c#120 (text) ==== Index: perl/hv.c --- perl/hv.c#119~18259~ Sun Dec 8 11:34:34 2002 +++ perl/hv.c Wed Jan 8 13:27:49 2003 @@ -506,7 +506,15 @@ stored within the hash (as in the case of tied hashes). Otherwise it can be dereferenced to get the original C<SV*>. Note that the caller is responsible for suitably incrementing the reference count of C<val> before -the call, and decrementing it if the function returned NULL. +the call, and decrementing it if the function returned NULL. Effectively +a successful hv_store takes ownership of one reference to C<val>. This is +usually what you want; a newly created SV has a reference count of one, so +if all your code does is create SVs then store them in a hash, hv_store +will own the only reference to the new SV, and your code doesn't need to do +anything further to tidy up. hv_store is not implemented as a call to +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 hv_store in preference to +hv_store_ent. See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more information on how to use this function on tied hashes. @@ -681,7 +689,17 @@ contents of the return value can be accessed using the C<He?> macros described here. Note that the caller is responsible for suitably incrementing the reference count of C<val> before the call, and -decrementing it if the function returned NULL. +decrementing it if the function returned NULL. Effectively a successful +hv_store_ent takes ownership of one reference to C<val>. This is +usually what you want; a newly created SV has a reference count of one, so +if all your code does is create SVs then store them in a hash, 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 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. hv_store +is not implemented as a call to 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 +hv_store in preference to hv_store_ent. See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more information on how to use this function on tied hashes. End of Patch.