sv_setsv(ST(0), sv);
This code tries to return a new SV (which contains the value 42) if it should
-return a real value, or undef otherwise. Instead it has returned a null
+return a real value, or undef otherwise. Instead it has returned a NULL
pointer which, somewhere down the line, will cause a segmentation violation,
bus error, or just weird results. Change the zero to C<&sv_undef> in the first
line and all will be well.
like $#array in Perl). If the array is empty, -1 is returned. The
C<av_fetch> function returns the value at index C<key>, but if C<lval>
is non-zero, then C<av_fetch> will store an undef value at that index.
-The C<av_store> function stores the value C<val> at index C<key>.
-note that C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s
-as their return value.
+The C<av_store> function stores the value C<val> at index C<key>, and does
+not increment the reference count of C<val>. Thus the caller is responsible
+for taking care of that, and if C<av_store> returns NULL, the caller will
+have to decrement the reference count to avoid a memory leak. Note that
+C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
+return value.
void av_clear(AV*);
void av_undef(AV*);
This returns NULL if the variable does not exist.
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use the array access functions on tied arrays.
+
=head2 Working with HVs
To create an HV, you use the following routine:
while (i--)
hash = hash * 33 + *s++;
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use the hash access functions on tied hashes.
+
=head2 Hash API Extensions
Beginning with version 5.004, the following functions are also supported:
HeKEY(HE* he)
HeKLEN(HE* he)
+Note that both C<hv_store> and C<hv_store_ent> do not increment the
+reference count of the stored C<val>, which is the caller's responsibility.
+If these functions return a NULL value, the caller will usually have to
+decrement the reference count of C<val> to avoid a memory leak.
=head2 References
The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
structure. If it is not the same as the C<sv> argument, the reference
count of the C<obj> object is incremented. If it is the same, or if
-the C<how> argument is "#", or if it is a null pointer, then C<obj> is
+the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is
merely stored, without the reference count being incremented.
There is also a function to add magic to an C<HV>:
field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
the mg_type field is changed to be the lowercase letter.
+=head2 Understanding the Magic of Tied Hashes and Arrays
+
+Tied hashes and arrays are magical beasts of the 'P' magic type.
+Proper usage of the array and hash access functions on them requires
+understanding a few caveats.
+
+The C<av_store> function, when given a tied array argument, merely
+copies the magic of the array onto the value to be "stored", using
+C<mg_copy>. It may also return NULL, indicating that the value did not
+actually need to be stored in the array. After a call to C<av_store> on
+a tied array, the caller will usually need to call C<mg_get(val)> to
+actually invoke the perl level "STORE" method on the TIEARRAY object. If
+C<av_store> did return NULL, a call to C<SvREFCNT_dec(val)> will also be
+usually necessary to avoid a memory leak.
+
+The previous paragraph is applicable verbatim to tied hash access using the
+C<hv_store> and C<hv_store_ent> functions as well.
+
+C<av_fetch> and the corresponding hash functions C<hv_fetch> and
+C<hv_fetch_ent> actually return an undefined mortal value whose magic
+has been initialized using C<mg_copy>. Note the value so returned does not
+need to be deallocated, as it is already mortal. But you will need to
+call C<mg_get()> on the returned value in order to actually invoke the
+perl level "FETCH" method on the underlying TIE object. Similarly,
+you may also call C<mg_set()> on the return value after possibly assigning
+a suitable value to it using C<sv_setsv>, which will invoke the "STORE"
+method on the TIE object.
+
+In other words, the array or hash fetch/store functions don't really
+fetch and store actual values in the case of tied arrays and hashes. They
+merely call C<mg_copy> to attach magic to the values that were meant to be
+"stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually
+do the job of invoking the TIE methods on the underlying objects. Thus
+the magic mechanism actually implements a kind of lazy access to arrays
+and hashes.
+
+Currently (as of perl version 5.004), use of the hash and array access
+functions requires the user to be aware of whether they are operating on
+"normal" hashes and arrays, or on their tied variants. A simpler API
+interface that provides transparent access to both tied and normal data
+types may be available in future versions.
+
+You would do well to understand that the TIEARRAY and TIEHASH interfaces
+are mere sugar to invoke some perl method calls while using the uniform hash
+and array syntax. The use of this sugar imposes some overhead (typically
+about two to four extra opcodes per FETCH/STORE operation, in addition to
+the creation of all the mortal variables required to invoke the methods).
+This overhead will be comparatively small if the TIE methods are themselves
+substantial, but if they are only a few statements long, the overhead
+will not be insignificant.
+
=head1 Subroutines
=head2 XSUBs and the Argument Stack
index. If C<lval> is set then the fetch will be part of a store. Check
that the return value is non-null before dereferencing it to a C<SV*>.
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied arrays.
+
SV** av_fetch _((AV* ar, I32 key, I32 lval));
=item av_len
=item av_store
Stores an SV in an array. The array index is specified as C<key>. The
-return value will be null if the operation failed, otherwise it can be
-dereferenced to get the original C<SV*>.
+return value will be NULL if the operation failed or if the value did not
+need to be actually stored within the array (as in the case of tied arrays).
+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.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied arrays.
SV** av_store _((AV* ar, I32 key, SV* val));
Deletes a key/value pair in the hash. The value SV is removed from the hash
and returned to the caller. The C<klen> is the length of the key. The
-C<flags> value will normally be zero; if set to G_DISCARD then null will be
+C<flags> value will normally be zero; if set to G_DISCARD then NULL will be
returned.
SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
Deletes a key/value pair in the hash. The value SV is removed from the hash
and returned to the caller. The C<flags> value will normally be zero; if set
-to G_DISCARD then null will be returned. C<hash> can be a valid precomputed
+to G_DISCARD then NULL will be returned. C<hash> can be a valid precomputed
hash value, or 0 to ask for it to be computed.
SV* hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash));
part of a store. Check that the return value is non-null before
dereferencing it to a C<SV*>.
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
+
SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
=item hv_fetch_ent
is a pointer to a static location, so be sure to make a copy of the
structure if you need to store it somewhere.
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
+
HE* hv_fetch_ent _((HV* tb, SV* key, I32 lval, U32 hash));
=item hv_free_ent
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, otherwise it can be dereferenced to get the
-original C<SV*>.
+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.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
parameter is the precomputed hash value; if it is zero then Perl will
compute it. The return value is the new hash entry so created. It will be
-null if the operation failed or if the entry was stored in a tied hash.
-Otherwise the contents of the return value can be accessed using the
-C<He???> macros described here.
+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 the
+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.
+
+See L<Understanding the Magic of Tied Hashes and Arrays> for more
+information on how to use this function on tied hashes.
HE* hv_store_ent _((HV* tb, SV* key, SV* val, U32 hash));
Returns the AV of the specified Perl array. If C<create> is set and the
Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then null is returned.
+set and the variable does not exist then NULL is returned.
AV* perl_get_av _((char* name, I32 create));
Returns the CV of the specified Perl sub. If C<create> is set and the Perl
variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then null is returned.
+set and the variable does not exist then NULL is returned.
CV* perl_get_cv _((char* name, I32 create));
Returns the HV of the specified Perl hash. If C<create> is set and the Perl
variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then null is returned.
+set and the variable does not exist then NULL is returned.
HV* perl_get_hv _((char* name, I32 create));
Returns the SV of the specified Perl scalar. If C<create> is set and the
Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then null is returned.
+set and the variable does not exist then NULL is returned.
SV* perl_get_sv _((char* name, I32 create));
=head1 DATE
-Version 31.7: 1997/5/1
+Version 31.8: 1997/5/17
projects / p5sagit/p5-mst-13.2.git / commitdiff