From 4f646c4b26915412bb507865c6f55c881755e8b8 Mon Sep 17 00:00:00 2001 From: Nicholas Clark Date: Wed, 1 Jan 2003 18:17:59 +0000 Subject: [PATCH] [DOCPATCH] hv_store and hv_store_ent Message-ID: <20030101181757.GB296@Bagpuss.unfortu.net> (Integrated from change #18399 from maint-5.8) p4raw-link: @18399 on //depot/maint-5.8/perl: b2b6dc3cf24b6bbbd2bcc5f30ade990aeb310850 p4raw-id: //depot/perl@18463 p4raw-integrated: from //depot/maint-5.8/perl@18462 'merge in' hv.c (@18271..) --- hv.c | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/hv.c b/hv.c index 7b79123..c2c824b 100644 --- a/hv.c +++ b/hv.c @@ -506,7 +506,15 @@ NULL if the operation failed or if the value did not need to be actually stored within the hash (as in the case of tied hashes). Otherwise it can be dereferenced to get the original C. Note that the caller is responsible for suitably incrementing the reference count of C 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. 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 for more information on how to use this function on tied hashes. @@ -681,7 +689,17 @@ stored within the hash (as in the case of tied hashes). Otherwise the contents of the return value can be accessed using the C macros described here. Note that the caller is responsible for suitably incrementing the reference count of C 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. 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; +unlike C it does not take ownership of it, so maintaining the correct +reference count on C 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 for more information on how to use this function on tied hashes. -- 1.8.3.1