The types are:
SVt_NULL
- SVt_BIND (unused)
SVt_IV
SVt_NV
SVt_RV
typedef enum {
SVt_NULL, /* 0 */
- SVt_BIND, /* 1 */
+ SVt_DUMMY, /* 1 */
SVt_IV, /* 2 */
SVt_NV, /* 3 */
/* RV was here, before it was merged with IV. */
Returns the value of the object's reference count.
=for apidoc Am|SV*|SvREFCNT_inc|SV* sv
-Increments the reference count of the given SV.
+Increments the reference count of the given SV, returning the SV.
All of the following SvREFCNT_inc* macros are optimized versions of
SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
and faster.
=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV.
+Decrements the reference count of the given SV. I<sv> may be NULL.
=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
Same as SvREFCNT_dec, but can only be used if you know I<sv>
them all by using a consistent macro. */
#define SvIS_FREED(sv) ((sv)->sv_flags == SVTYPEMASK)
-#define SvUPGRADE(sv, mt) (SvTYPE(sv) >= (mt) || (sv_upgrade(sv, mt), 1))
+/* this is defined in this peculiar way to avoid compiler warnings.
+ * See the <20121213131428.GD1842@iabyn.com> thread in p5p */
+#define SvUPGRADE(sv, mt) \
+ ((void)(SvTYPE(sv) >= (mt) || (sv_upgrade(sv, mt),1)))
#define SVf_IOK 0x00000100 /* has valid public integer value */
#define SVf_NOK 0x00000200 /* has valid public numeric value */
Tells an SV that it is an integer and disables all other OK bits.
=for apidoc Am|void|SvIOK_only_UV|SV* sv
-Tells and SV that it is an unsigned integer and disables all other OK bits.
+Tells an SV that it is an unsigned integer and disables all other OK bits.
=for apidoc Am|bool|SvIOK_UV|SV* sv
-Returns a boolean indicating whether the SV contains an unsigned integer.
+Returns a boolean indicating whether the SV contains an integer that must be
+interpreted as unsigned. A non-negative integer whose value is within the
+range of both an IV and a UV may be be flagged as either SvUOK or SVIOK.
=for apidoc Am|bool|SvUOK|SV* sv
-Returns a boolean indicating whether the SV contains an unsigned integer.
+Returns a boolean indicating whether the SV contains an integer that must be
+interpreted as unsigned. A non-negative integer whose value is within the
+range of both an IV and a UV may be be flagged as either SvUOK or SVIOK.
=for apidoc Am|bool|SvIOK_notUV|SV* sv
Returns a boolean indicating whether the SV contains a signed integer.
=for apidoc Am|char*|SvPVX|SV* sv
Returns a pointer to the physical string in the SV. The SV must contain a
-string.
+string. Prior to 5.9.3 it is not safe to execute this macro unless the SV's
+type >= SVt_PV.
This is also used to store the name of an autoloaded subroutine in an XS
AUTOLOAD routine. See L<perlguts/Autoloading with XSUBs>.
#define assert_not_ROK(sv) assert_(!SvROK(sv) || !SvRV(sv))
#define assert_not_glob(sv) assert_(!isGV_with_GP(sv))
-#define SvOK(sv) ((SvTYPE(sv) == SVt_BIND) \
- ? (SvFLAGS(SvRV(sv)) & SVf_OK \
- || isREGEXP(SvRV(sv))) \
- : (SvFLAGS(sv) & SVf_OK \
- || isREGEXP(sv)))
+#define SvOK(sv) (SvFLAGS(sv) & SVf_OK || isREGEXP(sv))
#define SvOK_off(sv) (assert_not_ROK(sv) assert_not_glob(sv) \
SvFLAGS(sv) &= ~(SVf_OK| \
SVf_IVisUV|SVf_UTF8), \
=for apidoc Am|U32|SvUTF8|SV* sv
Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up
properly, this indicates whether or not the SV contains UTF-8 encoded data.
-Call this after SvPV() in case any call to string overloading updates the
-internal flag.
+You should use this I<after> a call to SvPV() or one of its variants, in
+case any call to string overloading updates the internal flag.
=for apidoc Am|void|SvUTF8_on|SV *sv
Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
/*
=for apidoc Am|char*|SvPV_force|SV* sv|STRLEN len
Like C<SvPV> but will force the SV into containing a string (C<SvPOK>), and
-only a string (C<SvPOK_only>), by hook or by crook. You want force if you are
+only a string (C<SvPOK_only>), by hook or by crook. You need force if you are
going to update the C<SvPVX> directly. Processes get magic.
+Note that coercing an arbitrary scalar into a plain PV will potentially
+strip useful data from it. For example if the SV was C<SvROK>, then the
+referent will have its reference count decremented, and the SV itself may
+be converted to an C<SvPOK> scalar with a string buffer containing a value
+such as C<"ARRAY(0x1234)">.
+
=for apidoc Am|char*|SvPV_force_nomg|SV* sv|STRLEN len
-Like C<SvPV> but will force the SV into containing a string (C<SvPOK>), and
-only a string (C<SvPOK_only>), by hook or by crook. You want force if you are
-going to update the C<SvPVX> directly. Doesn't process get magic.
+Like C<SvPV_force>, but doesn't process get magic.
=for apidoc Am|char*|SvPV|SV* sv|STRLEN len
Returns a pointer to the string in the SV, or a stringified form of
stringified version becoming C<SvPOK>. Handles 'get' magic. See also
C<SvPVx> for a version which guarantees to evaluate sv only once.
+Note that there is no guarantee that the return value of C<SvPV()> is
+equal to C<SvPVX(sv)>, or that C<SvPVX(sv)> contains valid data, or that
+successive calls to C<SvPV(sv)) will return the same pointer value each
+time. This is due to the way that things like overloading and
+Copy-On-Write are handled. In these cases, the return value may point to
+a temporary buffer or similar. If you absolutely need the SvPVX field to
+be valid (for example, if you intend to write to it), then see
+L</SvPV_force>.
+
=for apidoc Am|char*|SvPVx|SV* sv|STRLEN len
A version of C<SvPV> which guarantees to evaluate C<sv> only once.
Only use this if C<sv> is an expression with side effects, otherwise use the
Like C<SvPV> but doesn't process magic.
=for apidoc Am|char*|SvPV_nolen|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. The SV may cache the
-stringified form becoming C<SvPOK>. Handles 'get' magic.
+Like C<SvPV> but doesn't set a length variable.
=for apidoc Am|char*|SvPV_nomg_nolen|SV* sv
Like C<SvPV_nolen> but doesn't process magic.
=for apidoc Am|UV|SvUVx|SV* sv
Coerces the given SV to an unsigned integer and
-returns it. Guarantees to C<sv> only once. Only
+returns it. Guarantees to evaluate C<sv> only once. Only
use this if C<sv> is an expression with side effects,
otherwise use the more efficient C<SvUV>.
#define SvTRUE_common(sv,fallback) ( \
!SvOK(sv) \
? 0 \
- : (SvFLAGS(sv) & (SVf_POK|SVf_IOK|SVf_NOK)) \
- ? ( (SvPOK(sv) && SvPVXtrue(sv)) \
- || (SvIOK(sv) && SvIVX(sv) != 0) \
+ : SvPOK(sv) \
+ ? SvPVXtrue(sv) \
+ : (SvFLAGS(sv) & (SVf_IOK|SVf_NOK)) \
+ ? ( (SvIOK(sv) && SvIVX(sv) != 0) \
|| (SvNOK(sv) && SvNVX(sv) != 0.0)) \
: (fallback))
Expands the character buffer in the SV so that it has room for the
indicated number of bytes (remember to reserve space for an extra trailing
NUL character). Calls C<sv_grow> to perform the expansion if necessary.
-Returns a pointer to the character buffer.
+Returns a pointer to the character buffer. SV must be of type >= SVt_PV. One
+alternative is to call C<sv_grow> if you are not sure of the type of SV.
=cut
*/
#define SvPEEK(sv) ""
#endif
-#define SvIMMORTAL(sv) ((sv)==&PL_sv_undef || (sv)==&PL_sv_yes || (sv)==&PL_sv_no || (sv)==&PL_sv_placeholder)
+#define SvIMMORTAL(sv) (SvREADONLY(sv) && ((sv)==&PL_sv_undef || (sv)==&PL_sv_yes || (sv)==&PL_sv_no || (sv)==&PL_sv_placeholder))
+
+#ifdef DEBUGGING
+ /* exercise the immortal resurrection code in sv_free2() */
+# define SvREFCNT_IMMORTAL 1000
+#else
+# define SvREFCNT_IMMORTAL ((~(U32)0)/2)
+#endif
/*
=for apidoc Am|SV *|boolSV|bool b
https://perl5.git.perl.org / perl5.git / blobdiff