+/*
+=for apidoc hv_store
+
+Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
+the length of the key. The C<hash> parameter is the precomputed hash
+value; if it is zero then Perl will compute it. The return value will be
+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<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. 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.
+
+=cut
+*/
+
+SV**
+Perl_hv_store(pTHX_ HV *hv, const char *key, I32 klen, SV *val, U32 hash)
+{
+ bool is_utf8 = FALSE;
+ const char *keysave = key;
+ int flags = 0;
+
+ if (klen < 0) {
+ klen = -klen;
+ is_utf8 = TRUE;
+ }
+
+ if (is_utf8) {
+ STRLEN tmplen = klen;
+ /* Just casting the &klen to (STRLEN) won't work well
+ * if STRLEN and I32 are of different widths. --jhi */
+ key = (char*)bytes_from_utf8((U8*)key, &tmplen, &is_utf8);
+ klen = tmplen;
+ /* If we were able to downgrade here, then than means that we were
+ passed in a key which only had chars 0-255, but was utf8 encoded. */
+ if (is_utf8)
+ flags = HVhek_UTF8;
+ /* If we found we were able to downgrade the string to bytes, then
+ we should flag that it needs upgrading on keys or each. */
+ if (key != keysave)
+ flags |= HVhek_WASUTF8 | HVhek_FREEKEY;
+ }
+
+ return hv_store_flags (hv, key, klen, val, hash, flags);
+}
+