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>.
}
/*
-=for apidoc Am|HV *|hv_copy_hints_hv|HV *ohv
+=for apidoc hv_copy_hints_hv
A specialised version of L</newHVhv> for copying C<%^H>. C<ohv> must be
a pointer to a hash (which may have C<%^H> magic, but should be generally
if (iter->xhv_name_u.xhvnameu_name) {
if(iter->xhv_name_count) {
if(flags & HV_NAME_SETALL) {
- HEK ** const name = HvAUX(hv)->xhv_name_u.xhvnameu_names;
- HEK **hekp = name + (
+ HEK ** const this_name = HvAUX(hv)->xhv_name_u.xhvnameu_names;
+ HEK **hekp = this_name + (
iter->xhv_name_count < 0
? -iter->xhv_name_count
: iter->xhv_name_count
);
- while(hekp-- > name+1)
+ while(hekp-- > this_name+1)
unshare_hek_or_pvn(*hekp, 0, 0, 0);
/* The first elem may be null. */
- if(*name) unshare_hek_or_pvn(*name, 0, 0, 0);
- Safefree(name);
+ if(*this_name) unshare_hek_or_pvn(*this_name, 0, 0, 0);
+ Safefree(this_name);
iter = HvAUX(hv); /* may been realloced */
spot = &iter->xhv_name_u.xhvnameu_name;
iter->xhv_name_count = 0;
restricted hashes may change, and the implementation currently is
insufficiently abstracted for any change to be tidy.
+=for apidoc Amnh||HV_ITERNEXT_WANTPLACEHOLDERS
+
=cut
*/
}
/*
-=for apidoc m|HV *|refcounted_he_chain_2hv|const struct refcounted_he *c|U32 flags
+=for apidoc refcounted_he_chain_2hv
Generates and returns a C<HV *> representing the content of a
C<refcounted_he> chain.
}
/*
-=for apidoc m|SV *|refcounted_he_fetch_pvn|const struct refcounted_he *chain|const char *keypv|STRLEN keylen|U32 hash|U32 flags
+=for apidoc refcounted_he_fetch_pvn
Search along a C<refcounted_he> chain for an entry with the key specified
by C<keypv> and C<keylen>. If C<flags> has the C<REFCOUNTED_HE_KEY_UTF8>
}
/*
-=for apidoc m|SV *|refcounted_he_fetch_pv|const struct refcounted_he *chain|const char *key|U32 hash|U32 flags
+=for apidoc refcounted_he_fetch_pv
Like L</refcounted_he_fetch_pvn>, but takes a nul-terminated string
instead of a string/length pair.
}
/*
-=for apidoc m|SV *|refcounted_he_fetch_sv|const struct refcounted_he *chain|SV *key|U32 hash|U32 flags
+=for apidoc refcounted_he_fetch_sv
Like L</refcounted_he_fetch_pvn>, but takes a Perl scalar instead of a
string/length pair.
}
/*
-=for apidoc m|struct refcounted_he *|refcounted_he_new_pvn|struct refcounted_he *parent|const char *keypv|STRLEN keylen|U32 hash|SV *value|U32 flags
+=for apidoc refcounted_he_new_pvn
Creates a new C<refcounted_he>. This consists of a single key/value
pair and a reference to an existing C<refcounted_he> chain (which may
}
/*
-=for apidoc m|struct refcounted_he *|refcounted_he_new_pv|struct refcounted_he *parent|const char *key|U32 hash|SV *value|U32 flags
+=for apidoc refcounted_he_new_pv
Like L</refcounted_he_new_pvn>, but takes a nul-terminated string instead
of a string/length pair.
}
/*
-=for apidoc m|struct refcounted_he *|refcounted_he_new_sv|struct refcounted_he *parent|SV *key|U32 hash|SV *value|U32 flags
+=for apidoc refcounted_he_new_sv
Like L</refcounted_he_new_pvn>, but takes a Perl scalar instead of a
string/length pair.
}
/*
-=for apidoc m|void|refcounted_he_free|struct refcounted_he *he
+=for apidoc refcounted_he_free
Decrements the reference count of a C<refcounted_he> by one. If the
reference count reaches zero the structure's memory is freed, which
}
/*
-=for apidoc m|struct refcounted_he *|refcounted_he_inc|struct refcounted_he *he
+=for apidoc refcounted_he_inc
Increment the reference count of a C<refcounted_he>. The pointer to the
C<refcounted_he> is also returned. It is safe to pass a null pointer
/*
=for apidoc cop_fetch_label
-Returns the label attached to a cop.
-The flags pointer may be set to C<SVf_UTF8> or 0.
+Returns the label attached to a cop, and stores its length in bytes into
+C<*len>.
+Upon return, C<*flags> will be set to either C<SVf_UTF8> or 0.
+
+Alternatively, use the macro L</C<CopLABEL_len_flags>>;
+or if you don't need to know if the label is UTF-8 or not, the macro
+L</C<CopLABEL_len>>;
+or if you additionally dont need to know the length, L</C<CopLABEL>>.
=cut
*/
Save a label into a C<cop_hints_hash>.
You need to set flags to C<SVf_UTF8>
-for a UTF-8 label.
+for a UTF-8 label. Any other flag is ignored.
=cut
*/