SvIV(SV*)
SvNV(SV*)
SvPV(SV*, STRLEN len)
+ SvPV_nolen(SV*)
which will automatically coerce the actual scalar type into an IV, double,
or string.
In the C<SvPV> macro, the length of the string returned is placed into the
-variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
-care what the length of the data is, use the global variable C<PL_na>, though
-this is rather less efficient than using a local variable. Remember,
-however, that Perl allows arbitrary strings of data that may both contain
-NULs and might not be terminated by a NUL.
+variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do
+not care what the length of the data is, use the C<SvPV_nolen> macro.
+Historically the C<SvPV> macro with the global variable C<PL_na> has been
+used in this case. But that can be quite inefficient because C<PL_na> must
+be accessed in thread-local storage in threaded Perl. In any case, remember
+that Perl allows arbitrary strings of data that may both contain NULs and
+might not be terminated by a NUL.
If you want to know if the scalar value is TRUE, you can use:
The C<av_clear> function deletes all the elements in the AV* array, but
does not actually delete the array itself. The C<av_undef> function will
delete all the elements in the array plus the array itself. The
-C<av_extend> function extends the array so that it contains C<key>
-elements. If C<key> is less than the current length of the array, then
-nothing is done.
+C<av_extend> function extends the array so that it contains at least C<key+1>
+elements. If C<key+1> is less than the currently allocated length of the array,
+then nothing is done.
If you know the name of an array variable, you can get a pointer to its AV
by using the following:
I<pseudo-block>, and arrange for some changes to be automatically
undone at the end of it, either explicit, or via a non-local exit (via
die()). A I<block>-like construct is created by a pair of
-C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a
-Scalar">). Such a construct may be created specially for some
-important localized task, or an existing one (like boundaries of
-enclosing Perl subroutine/block, or an existing pair for freeing TMPs)
-may be used. (In the second case the overhead of additional
-localization must be almost negligible.) Note that any XSUB is
-automatically enclosed in an C<ENTER>/C<LEAVE> pair.
+C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">).
+Such a construct may be created specially for some important localized
+task, or an existing one (like boundaries of enclosing Perl
+subroutine/block, or an existing pair for freeing TMPs) may be
+used. (In the second case the overhead of additional localization must
+be almost negligible.) Note that any XSUB is automatically enclosed in
+an C<ENTER>/C<LEAVE> pair.
Inside such a I<pseudo-block> the following service is available:
=head2 Memory Allocation
-It is suggested that you use the version of malloc that is distributed
+All memory meant to be used with the Perl API functions should be manipulated
+using the macros described in this section. The macros provide the necessary
+transparency between differences in the actual malloc implementation that is
+used within perl.
+
+It is suggested that you enable the version of malloc that is distributed
with Perl. It keeps pools of various sizes of unallocated memory in
order to satisfy allocation requests more quickly. However, on some
platforms, it may cause spurious malloc or free errors.
with C<perl> be referenced with an explicit C<Perl_> prefix.
The sort order of the listing is case insensitive, with any
-occurrences of '_' ignored for the the purpose of sorting.
+occurrences of '_' ignored for the purpose of sorting.
=over 8
int mg_set (SV* sv)
+=item modglobal
+
+C<modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+
=item Move
The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
A convenience variable which is typically used with C<SvPV> when one doesn't
care about the length of the string. It is usually more efficient to
-declare a local variable and use that instead.
+either declare a local variable and use that instead or to use the C<SvPV_nolen>
+macro.
=item New
=item SvIV
-Returns the integer which is in the SV.
+Coerces the given SV to an integer and returns it.
int SvIV (SV* sv)
=item SvIVX
-Returns the integer which is stored in the SV.
+Returns the integer which is stored in the SV, assuming SvIOK is true.
int SvIVX (SV* sv)
=item SvNV
-Returns the double which is stored in the SV.
+Coerce the given SV to a double and return it.
double SvNV (SV* sv)
=item SvNVX
-Returns the double which is stored in the SV.
+Returns the double which is stored in the SV, assuming SvNOK is true.
double SvNVX (SV* sv)
Returns a pointer to the string in the SV, or a stringified form of the SV
if the SV does not contain a string. Handles 'get' magic.
- char* SvPV (SV* sv, int len )
+ char* SvPV (SV* sv, int len)
=item SvPV_force
char* SvPV_force(SV* sv, int len)
+=item SvPV_nolen
+
+Returns a pointer to the string in the SV, or a stringified form of the SV
+if the SV does not contain a string. Handles 'get' magic.
+
+ char* SvPV (SV* sv)
=item SvPVX
=item SvUV
-Returns the unsigned integer which is in the SV.
+Coerces the given SV to an unsigned integer and returns it.
UV SvUV(SV* sv)
=item SvUVX
-Returns the unsigned integer which is stored in the SV.
+Returns the unsigned integer which is stored in the SV, assuming SvIOK is true.
UV SvUVX(SV* sv)
https://perl5.git.perl.org / perl5.git / blobdiff