These are most easily explained from the bottom up.
-SVt_PVIO is for I/O objects, SVt_PVFM for formats, SVt_PVCV for
-subroutines, SVt_PVHV for hashes and SVt_PVAV for arrays.
+C<SVt_PVIO> is for I/O objects, C<SVt_PVFM> for formats, C<SVt_PVCV> for
+subroutines, C<SVt_PVHV> for hashes and C<SVt_PVAV> for arrays.
All the others are scalar types, that is, things that can be bound to a
C<$> variable. For these, the internal types are mostly orthogonal to
Hence, checking C<< SvTYPE(sv) < SVt_PVAV >> is the best way to see whether
something is a scalar.
-SVt_PVGV represents a typeglob. If !SvFAKE(sv), then it is a real,
-incoercible typeglob. If SvFAKE(sv), then it is a scalar to which a
+C<SVt_PVGV> represents a typeglob. If C<!SvFAKE(sv)>, then it is a real,
+incoercible typeglob. If C<SvFAKE(sv)>, then it is a scalar to which a
typeglob has been assigned. Assigning to it again will stop it from being
-a typeglob. SVt_PVLV represents a scalar that delegates to another scalar
+a typeglob. C<SVt_PVLV> represents a scalar that delegates to another scalar
behind the scenes. It is used, e.g., for the return value of C<substr> and
for tied hash and array elements. It can hold any scalar value, including
-a typeglob. SVt_REGEXP is for regular
-expressions. SVt_INVLIST is for Perl
+a typeglob. C<SVt_REGEXP> is for regular
+expressions. C<SVt_INVLIST> is for Perl
core internal use only.
-SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression,
+C<SVt_PVMG> represents a "normal" scalar (not a typeglob, regular expression,
or delegate). Since most scalars do not need all the internal fields of a
PVMG, we save memory by allocating smaller structs when possible. All the
-other types are just simpler forms of SVt_PVMG, with fewer internal fields.
- SVt_NULL can only hold undef. SVt_IV can hold undef, an integer, or a
-reference. (SVt_RV is an alias for SVt_IV, which exists for backward
-compatibility.) SVt_NV can hold any of those or a double. SVt_PV can only
-hold undef or a string. SVt_PVIV is a superset of SVt_PV and SVt_IV.
-SVt_PVNV is similar. SVt_PVMG can hold anything SVt_PVNV can hold, but it
+other types are just simpler forms of C<SVt_PVMG>, with fewer internal fields.
+C<SVt_NULL> can only hold undef. C<SVt_IV> can hold undef, an integer, or a
+reference. (C<SVt_RV> is an alias for C<SVt_IV>, which exists for backward
+compatibility.) C<SVt_NV> can hold any of those or a double. C<SVt_PV> can only
+hold C<undef> or a string. C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>.
+C<SVt_PVNV> is similar. C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
can, but does not have to, be blessed or magical.
=for apidoc AmU||SVt_NULL
#define SVt_MASK 0xf /* smallest bitmask that covers all types */
#ifndef PERL_CORE
-/* Although Fast Boyer Moore tables are now being stored in PVGVs, for most
- purposes external code wanting to consider PVBM probably needs to think of
- PVMG instead. */
+/* Fast Boyer Moore tables are now stored in magic attached to PVMGs */
# define SVt_PVBM SVt_PVMG
/* Anything wanting to create a reference from clean should ensure that it has
a scalar of type SVt_IV now: */
=head1 SV Manipulation Functions
=for apidoc Am|U32|SvREFCNT|SV* sv
-Returns the value of the object's reference count.
+Returns the value of the object's reference count. Exposed
+to perl code via Internals::SvREFCNT().
=for apidoc Am|SV*|SvREFCNT_inc|SV* 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.
+All of the following C<SvREFCNT_inc>* macros are optimized versions of
+C<SvREFCNT_inc>, and can be replaced with C<SvREFCNT_inc>.
=for apidoc Am|SV*|SvREFCNT_inc_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you know C<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_inc>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_void|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the
return value. The macro doesn't need to return a meaningful value.
=for apidoc Am|void|SvREFCNT_inc_void_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that C<sv> is not NULL. The macro doesn't need
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the return
+value, and you know that C<sv> is not C<NULL>. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|SV*|SvREFCNT_inc_simple|SV* sv
-Same as SvREFCNT_inc, but can only be used with expressions without side
+Same as C<SvREFCNT_inc>, but can only be used with expressions without side
effects. Since we don't have to store a temporary value, it's faster.
=for apidoc Am|SV*|SvREFCNT_inc_simple_NN|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you know C<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_inc_simple>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|void|SvREFCNT_inc_simple_void|SV* sv
-Same as SvREFCNT_inc_simple, but can only be used if you don't need the
+Same as C<SvREFCNT_inc_simple>, but can only be used if you don't need the
return value. The macro doesn't need to return a meaningful value.
=for apidoc Am|void|SvREFCNT_inc_simple_void_NN|SV* sv
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that C<sv> is not NULL. The macro doesn't need
+Same as C<SvREFCNT_inc>, but can only be used if you don't need the return
+value, and you know that C<sv> is not C<NULL>. The macro doesn't need
to return a meaningful value, or check for NULLness, so it's smaller
and faster.
=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV. C<sv> may be NULL.
+Decrements the reference count of the given SV. C<sv> may be C<NULL>.
=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
-Same as SvREFCNT_dec, but can only be used if you know C<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
+Same as C<SvREFCNT_dec>, but can only be used if you know C<sv>
+is not C<NULL>. Since we don't have to check the NULLness, it's faster
and smaller.
=for apidoc Am|svtype|SvTYPE|SV* sv
#define SVp_IOK 0x00001000 /* has valid non-public integer value */
#define SVp_NOK 0x00002000 /* has valid non-public numeric value */
#define SVp_POK 0x00004000 /* has valid non-public pointer value */
-#define SVp_SCREAM 0x00008000 /* method name is DOES */
- /* eval cx text is ref counted */
+#define SVp_SCREAM 0x00008000 /* currently unused on plain scalars */
#define SVphv_CLONEABLE SVp_SCREAM /* PVHV (stashes) clone its objects */
#define SVpgv_GP SVp_SCREAM /* GV has a valid GP */
#define SVprv_PCS_IMPORTED SVp_SCREAM /* RV is a proxy for a constant
subroutine in another package. Set the
GvIMPORTED_CV_on() if it needs to be
expanded to a real GV */
+
+/* SVf_PROTECT is what SVf_READONLY should have been: i.e. modifying
+ * this SV is completely illegal. However, SVf_READONLY (via
+ * Internals::SvREADONLY()) has come to be seen as a flag that can be
+ * temporarily set and unset by the user to indicate e.g. whether a hash
+ * is "locked". Now, Hash::Util et al only set SVf_READONLY, while core
+ * sets both (SVf_READONLY|SVf_PROTECT) to indicate both to core and user
+ * code that this SV should not be messed with.
+ */
#define SVf_PROTECT 0x00010000 /* very read-only */
#define SVs_PADTMP 0x00020000 /* in use as tmp */
#define SVs_PADSTALE 0x00040000 /* lexical has gone out of scope;
#define PRIVSHIFT 4 /* (SVp_?OK >> PRIVSHIFT) == SVf_?OK */
-/* Note that SVf_AMAGIC is now only set on stashes. */
+/* SVf_AMAGIC means that the stash *may* have have overload methods. It's
+ * set each time a function is compiled into a stash, and is reset by the
+ * overload code when called for the first time and finds that there are
+ * no overload methods. Note that this used to be set on the object; but
+ * is now only set on stashes.
+ */
#define SVf_AMAGIC 0x10000000 /* has magical overloaded methods */
#define SVf_IsCOW 0x10000000 /* copy on write (shared hash key if
SvLEN == 0) */
/* Some private flags. */
-/* The SVp_SCREAM|SVpbm_VALID (0x40008000) combination is up for grabs.
- Formerly it was used for pad names, but now it is available. The core
- is careful to avoid setting both flags.
-
- SVf_POK, SVp_POK also set:
- 0x00004400 Normal
- 0x0000C400 method name for DOES (SvSCREAM)
- 0x40004400 FBM compiled (SvVALID)
- 0x4000C400 *** Formerly used for pad names ***
-
- 0x00008000 GV with GP
- 0x00008800 RV with PCS imported
-*/
/* PVAV */
#define SVpav_REAL 0x40000000 /* free old entries */
/* PVHV */
#define SVphv_LAZYDEL 0x40000000 /* entry in xhv_eiter must be deleted */
-/* This is only set true on a PVGV when it's playing "PVBM", but is tested for
- on any regular scalar (anything <= PVLV) */
-#define SVpbm_VALID 0x40000000
-/* Only used in toke.c on an SV stored in PL_lex_repl */
-#define SVrepl_EVAL 0x40000000 /* Replacement part of s///e */
/* IV, PVIV, PVNV, PVMG, PVGV and (I assume) PVLV */
#define SVf_IVisUV 0x80000000 /* use XPVUV instead of XPVIV */
#define SVpav_REIFY 0x80000000 /* can become real */
/* PVHV */
#define SVphv_HASKFLAGS 0x80000000 /* keys have flag byte after hash */
-/* PVGV when SVpbm_VALID is true */
-#define SVpbm_TAIL 0x80000000
/* RV upwards. However, SVf_ROK and SVp_IOK are exclusive */
#define SVprv_WEAKREF 0x80000000 /* Weak reference */
/* pad name vars only */
union _xnvu {
NV xnv_nv; /* numeric value, if any */
HV * xgv_stash;
- struct {
- U32 xlow;
- U32 xhigh;
- } xpad_cop_seq; /* used by pad.c for cop_sequence */
+ line_t xnv_lines; /* used internally by S_scan_subst() */
+ bool xnv_bm_tail; /* an SvVALID (BM) SV has an implicit "\n" */
};
union _xivu {
IV xivu_iv; /* integer value */
UV xivu_uv;
HEK * xivu_namehek; /* xpvlv, xpvgv: GvNAME */
+ bool xivu_eval_seen; /* used internally by S_scan_subst() */
+
};
union _xmgu {
the list, merely toggle this flag */
};
-/* This structure works in 3 ways - regular scalar, GV with GP, or fast
- Boyer-Moore. */
+/* This structure works in 2 ways - regular scalar, or GV with GP */
+
struct xpvgv {
_XPV_HEAD;
union _xivu xiv_u;
* Perl_filter_add() tries to do with the dirp), hence the
* following union trick (as suggested by Gurusamy Sarathy).
* For further information see Geir Johansen's problem report
- * titled [ID 20000612.002] Perl problem on Cray system
+ * titled [ID 20000612.002 (#3366)] Perl problem on Cray system
* The any pointer (known as IoANY()) will also be a good place
* to hang any IO disciplines to.
*/
Unsets the IV status of an SV.
=for apidoc Am|void|SvIOK_only|SV* sv
-Tells an SV that it is an integer and disables all other OK bits.
+Tells an SV that it is an integer and disables all other C<OK> bits.
=for apidoc Am|void|SvIOK_only_UV|SV* sv
-Tells an 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 C<OK> bits.
=for apidoc Am|bool|SvIOK_UV|SV* sv
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.
+range of both an IV and a UV may be be flagged as either C<SvUOK> or C<SVIOK>.
=for apidoc Am|bool|SvUOK|SV* sv
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.
+range of both an IV and a UV may be be flagged as either C<SvUOK> or C<SVIOK>.
=for apidoc Am|bool|SvIOK_notUV|SV* sv
Returns a boolean indicating whether the SV contains a signed integer.
Unsets the PV status of an SV.
=for apidoc Am|void|SvPOK_only|SV* sv
-Tells an SV that it is a string and disables all other OK bits.
+Tells an SV that it is a string and disables all other C<OK> bits.
Will also turn off the UTF-8 status.
=for apidoc Am|bool|SvVOK|SV* sv
=for apidoc Am|U32|SvOOK|SV* sv
Returns a U32 indicating whether the pointer to the string buffer is offset.
This hack is used internally to speed up removal of characters from the
-beginning of a SvPV. When SvOOK is true, then the start of the
-allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
-This offset used to be stored in SvIVX, but is now stored within the spare
+beginning of a C<SvPV>. When C<SvOOK> is true, then the start of the
+allocated string buffer is actually C<SvOOK_offset()> bytes before C<SvPVX>.
+This offset used to be stored in C<SvIVX>, but is now stored within the spare
part of the buffer.
=for apidoc Am|U32|SvROK|SV* sv
=for apidoc Am|IV|SvIVX|SV* sv
Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<L</SvIV>>.
+Only use when you are sure C<SvIOK> is true. See also C<L</SvIV>>.
=for apidoc Am|UV|SvUVX|SV* sv
Returns the raw value in the SV's UV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<L</SvUV>>.
+Only use when you are sure C<SvIOK> is true. See also C<L</SvUV>>.
=for apidoc Am|NV|SvNVX|SV* sv
Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<L</SvNV>>.
+Only use when you are sure C<SvNOK> is true. See also C<L</SvNV>>.
=for apidoc Am|char*|SvPVX|SV* sv
Returns a pointer to the physical string in the SV. The SV must contain a
string. Prior to 5.9.3 it is not safe
to execute this macro unless the SV's
-type >= SVt_PV.
+type >= C<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>.
Returns a pointer to the spot just after the last character in
the string which is in the SV, where there is usually a trailing
C<NUL> character (even though Perl scalars do not strictly require it).
-See C<L</SvCUR>>. Access the character as *(SvEND(sv)).
+See C<L</SvCUR>>. Access the character as C<*(SvEND(sv))>.
Warning: If C<SvCUR> is equal to C<SvLEN>, then C<SvEND> points to
unallocated memory.
C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
=for apidoc Am|void|SvNV_set|SV* sv|NV val
-Set the value of the NV pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the NV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvPV_set|SV* sv|char* val
This is probably not what you want to use, you probably wanted
Remember to free the previous PV buffer. There are many things to check.
Beware that the existing pointer may be involved in copy-on-write or other
mischief, so do C<SvOOK_off(sv)> and use C<sv_force_normal> or
-C<SvPV_force> (or check the SvIsCOW flag) first to make sure this
+C<SvPV_force> (or check the C<SvIsCOW> flag) first to make sure this
modification is safe. Then finally, if it is not a COW, call C<SvPV_free> to
free the previous PV buffer.
=for apidoc Am|void|SvUV_set|SV* sv|UV val
-Set the value of the UV pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the UV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvRV_set|SV* sv|SV* val
-Set the value of the RV pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the RV pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvMAGIC_set|SV* sv|MAGIC* val
-Set the value of the MAGIC pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the MAGIC pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvSTASH_set|SV* sv|HV* val
-Set the value of the STASH pointer in sv to val. See C<L</SvIV_set>>.
+Set the value of the STASH pointer in C<sv> to val. See C<L</SvIV_set>>.
=for apidoc Am|void|SvCUR_set|SV* sv|STRLEN len
Set the current length of the string which is in the SV. See C<L</SvCUR>>
and C<SvIV_set>>.
=for apidoc Am|void|SvLEN_set|SV* sv|STRLEN len
-Set the actual length of the string which is in the SV. See C<L</SvIV_set>>.
+Set the size of the string buffer for the SV. See C<L</SvLEN>>.
=cut
*/
=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.
-You should use this I<after> a call to SvPV() or one of its variants, in
+You should use this I<after> a call to C<SvPV()> or one of its variants, in
case any call to string overloading updates the internal flag.
If you want to take into account the L<bytes> pragma, use C<L</DO_UTF8>>
Do not use frivolously.
=for apidoc Am|void|SvPOK_only_UTF8|SV* sv
-Tells an SV that it is a string and disables all other OK bits,
+Tells an SV that it is a string and disables all other C<OK> bits,
and leaves the UTF-8 status as it was.
=cut
#define SvOOK(sv) (SvFLAGS(sv) & SVf_OOK)
#define SvOOK_on(sv) (SvFLAGS(sv) |= SVf_OOK)
-#define SvOOK_off(sv) ((void)(SvOOK(sv) && sv_backoff(sv)))
+#define SvOOK_off(sv) ((void)(SvOOK(sv) && (sv_backoff(sv),0)))
#define SvFAKE(sv) (SvFLAGS(sv) & SVf_FAKE)
#define SvFAKE_on(sv) (SvFLAGS(sv) |= SVf_FAKE)
/*
=for apidoc m|U32|SvTHINKFIRST|SV *sv
-A quick flag check to see whether an sv should be passed to sv_force_normal
-to be "downgraded" before SvIVX or SvPVX can be modified directly.
+A quick flag check to see whether an C<sv> should be passed to C<sv_force_normal>
+to be "downgraded" before C<SvIVX> or C<SvPVX> can be modified directly.
-For example, if your scalar is a reference and you want to modify the SvIVX
-slot, you can't just do SvROK_off, as that will leak the referent.
+For example, if your scalar is a reference and you want to modify the C<SvIVX>
+slot, you can't just do C<SvROK_off>, as that will leak the referent.
This is used internally by various sv-modifying functions, such as
-sv_setsv, sv_setiv and sv_pvn_force.
+C<sv_setsv>, C<sv_setiv> and C<sv_pvn_force>.
One case that this does not handle is a gv without SvFAKE set. After
it will still be a gv.
-SvTHINKFIRST sometimes produces false positives. In those cases
-sv_force_normal does nothing.
+C<SvTHINKFIRST> sometimes produces false positives. In those cases
+C<sv_force_normal> does nothing.
=cut
*/
#define SvOBJECT_on(sv) (SvFLAGS(sv) |= SVs_OBJECT)
#define SvOBJECT_off(sv) (SvFLAGS(sv) &= ~SVs_OBJECT)
+/*
+=for apidoc Am|U32|SvREADONLY|SV* sv
+Returns true if the argument is readonly, otherwise returns false.
+Exposed to to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_on|SV* sv
+Mark an object as readonly. Exactly what this means depends on the object
+type. Exposed to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_off|SV* sv
+Mark an object as not-readonly. Exactly what this mean depends on the
+object type. Exposed to perl code via Internals::SvREADONLY().
+
+=cut
+*/
+
#define SvREADONLY(sv) (SvFLAGS(sv) & (SVf_READONLY|SVf_PROTECT))
#ifdef PERL_CORE
# define SvREADONLY_on(sv) (SvFLAGS(sv) |= (SVf_READONLY|SVf_PROTECT))
# define SvCOMPILED_off(sv)
#endif
-#define SvEVALED(sv) (SvFLAGS(sv) & SVrepl_EVAL)
-#define SvEVALED_on(sv) (SvFLAGS(sv) |= SVrepl_EVAL)
-#define SvEVALED_off(sv) (SvFLAGS(sv) &= ~SVrepl_EVAL)
#if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
-# define SvVALID(sv) ({ const SV *const _svvalid = (const SV*)(sv); \
- if (SvFLAGS(_svvalid) & SVpbm_VALID && !SvSCREAM(_svvalid)) \
- assert(!isGV_with_GP(_svvalid)); \
- (SvFLAGS(_svvalid) & SVpbm_VALID); \
- })
-# define SvVALID_on(sv) ({ SV *const _svvalid = MUTABLE_SV(sv); \
- assert(!isGV_with_GP(_svvalid)); \
- assert(!SvSCREAM(_svvalid)); \
- (SvFLAGS(_svvalid) |= SVpbm_VALID); \
- })
-# define SvVALID_off(sv) ({ SV *const _svvalid = MUTABLE_SV(sv); \
- assert(!isGV_with_GP(_svvalid)); \
- assert(!SvSCREAM(_svvalid)); \
- (SvFLAGS(_svvalid) &= ~SVpbm_VALID); \
- })
-
# define SvTAIL(sv) ({ const SV *const _svtail = (const SV *)(sv); \
assert(SvTYPE(_svtail) != SVt_PVAV); \
assert(SvTYPE(_svtail) != SVt_PVHV); \
- assert(!SvSCREAM(_svtail)); \
- (SvFLAGS(sv) & (SVpbm_TAIL|SVpbm_VALID)) \
- == (SVpbm_TAIL|SVpbm_VALID); \
+ assert(!(SvFLAGS(_svtail) & (SVf_NOK|SVp_NOK))); \
+ assert(SvVALID(_svtail)); \
+ ((XPVNV*)SvANY(_svtail))->xnv_u.xnv_bm_tail; \
})
#else
-# define SvVALID(sv) ((SvFLAGS(sv) & SVpbm_VALID) && !SvSCREAM(sv))
-# define SvVALID_on(sv) (SvFLAGS(sv) |= SVpbm_VALID)
-# define SvVALID_off(sv) (SvFLAGS(sv) &= ~SVpbm_VALID)
-# define SvTAIL(sv) ((SvFLAGS(sv) & (SVpbm_TAIL|SVpbm_VALID)) \
- == (SVpbm_TAIL|SVpbm_VALID))
-
+# define SvTAIL(_svtail) (((XPVNV*)SvANY(_svtail))->xnv_u.xnv_bm_tail)
#endif
-#define SvTAIL_on(sv) (SvFLAGS(sv) |= SVpbm_TAIL)
-#define SvTAIL_off(sv) (SvFLAGS(sv) &= ~SVpbm_TAIL)
+
+/* Does the SV have a Boyer-Moore table attached as magic?
+ * 'VALID' is a poor name, but is kept for historical reasons. */
+#define SvVALID(_svvalid) ( \
+ SvPOKp(_svvalid) \
+ && SvSMAGICAL(_svvalid) \
+ && SvMAGIC(_svvalid) \
+ && (SvMAGIC(_svvalid)->mg_type == PERL_MAGIC_bm \
+ || mg_find(_svvalid, PERL_MAGIC_bm)) \
+ )
#define SvRVx(sv) SvRV(sv)
#define SvTAINT(sv) \
STMT_START { \
- if (UNLIKELY(TAINTING_get)) { \
- if (UNLIKELY(TAINT_get)) \
- SvTAINTED_on(sv); \
- } \
+ assert(TAINTING_get || !TAINT_get); \
+ if (UNLIKELY(TAINT_get)) \
+ SvTAINTED_on(sv); \
} STMT_END
/*
stringified version becoming C<SvPOK>. Handles 'get' magic. The
C<len> variable will be set to the length of the string (this is a macro, so
don't use C<&len>). See also C<L</SvPVx>> for a version which guarantees to
-evaluate sv only once.
+evaluate C<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
+a temporary buffer or similar. If you absolutely need the C<SvPVX> field to
be valid (for example, if you intend to write to it), then see
C<L</SvPV_force>>.
=for apidoc Am|IV|SvIV|SV* sv
Coerces the given SV to an integer and returns it. See C<L</SvIVx>> for a
-version which guarantees to evaluate sv only once.
+version which guarantees to evaluate C<sv> only once.
=for apidoc Am|IV|SvIV_nomg|SV* sv
Like C<SvIV> but doesn't process magic.
=for apidoc Am|NV|SvNV|SV* sv
Coerce the given SV to a double and return it. See C<L</SvNVx>> for a version
-which guarantees to evaluate sv only once.
+which guarantees to evaluate C<sv> only once.
=for apidoc Am|NV|SvNV_nomg|SV* sv
Like C<SvNV> but doesn't process magic.
=for apidoc Am|UV|SvUV|SV* sv
Coerces the given SV to an unsigned integer and returns it. See C<L</SvUVx>>
-for a version which guarantees to evaluate sv only once.
+for a version which guarantees to evaluate C<sv> only once.
=for apidoc Am|UV|SvUV_nomg|SV* sv
Like C<SvUV> but doesn't process magic.
=for apidoc Am|bool|SvTRUE|SV* sv
Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Handles 'get' magic
-unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the
+false. See C<L</SvOK>> for a defined/undefined test. Handles 'get' magic
+unless the scalar is already C<SvPOK>, C<SvIOK> or C<SvNOK> (the public, not the
private flags).
=for apidoc Am|bool|SvTRUE_nomg|SV* sv
Returns a boolean indicating whether Perl would evaluate the SV as true or
-false. See SvOK() for a defined/undefined test. Does not handle 'get' magic.
+false. See C<L</SvOK>> for a defined/undefined test. Does not handle 'get' magic.
=for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
=for apidoc Am|char*|SvPVutf8|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to utf8 first if necessary.
+Like C<SvPV>, but converts C<sv> to UTF-8 first if necessary.
=for apidoc Am|char*|SvPVutf8_nolen|SV* sv
-Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to UTF-8 first if necessary.
=for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to byte representation first if necessary.
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVbyte_nolen|SV* sv
-Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to byte representation first if necessary.
=for apidoc Am|char*|SvPVutf8x_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
+Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVutf8_force>
otherwise.
=for apidoc Am|char*|SvPVutf8x|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
+Like C<SvPV>, but converts C<sv> to UTF-8 first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVutf8>
otherwise.
=for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
+Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte_force>
otherwise.
=for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
+Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte>
otherwise.
=for apidoc Am|U32|SvIsCOW|SV* sv
=for apidoc Amdb|STRLEN|sv_utf8_upgrade_nomg|NN SV *sv
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>.
+Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
=cut
*/
#define newRV_inc(sv) newRV(sv)
-/* the following macros update any magic values this sv is associated with */
+/* the following macros update any magic values this C<sv> is associated with */
/*
=head1 Magical Functions
argument more than once.
=for apidoc Am|void|SvSetSV|SV* dsv|SV* ssv
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+Calls C<sv_setsv> if C<dsv> is not the same as C<ssv>. May evaluate arguments
more than once. Does not handle 'set' magic on the destination SV.
=for apidoc Am|void|SvSetSV_nosteal|SV* dsv|SV* ssv
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
+Calls a non-destructive version of C<sv_setsv> if C<dsv> is not the same as
+C<ssv>. May evaluate arguments more than once.
=for apidoc Am|void|SvSetMagicSV|SV* dsv|SV* ssv
Like C<SvSetSV>, but does any set magic required afterwards.
Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
=for apidoc Am|void|SvSHARE|SV* sv
-Arranges for sv to be shared between threads if a suitable module
+Arranges for C<sv> to be shared between threads if a suitable module
has been loaded.
=for apidoc Am|void|SvLOCK|SV* sv
-Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+Arranges for a mutual exclusion lock to be obtained on C<sv> if a suitable module
has been loaded.
=for apidoc Am|void|SvUNLOCK|SV* sv
-Releases a mutual exclusion lock on sv if a suitable module
+Releases a mutual exclusion lock on C<sv> if a suitable module
has been loaded.
=head1 SV Manipulation Functions
indicated number of bytes (remember to reserve space for an extra trailing
C<NUL> character). Calls C<sv_grow> to perform the expansion if necessary.
Returns a pointer to the character
-buffer. SV must be of type >= SVt_PV. One
+buffer. SV must be of type >= C<SVt_PV>. One
alternative is to call C<sv_grow> if you are not sure of the type of SV.
+=for apidoc Am|char *|SvPVCLEAR|SV* sv
+Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
+properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
+
=cut
*/
+#define SvPVCLEAR(sv) sv_setpv_bufsize(sv,0,0)
#define SvSHARE(sv) PL_sharehook(aTHX_ sv)
#define SvLOCK(sv) PL_lockhook(aTHX_ sv)
#define SvUNLOCK(sv) PL_unlockhook(aTHX_ sv)
=for apidoc Am|SV*|newSVpvn_utf8|NULLOK const char* s|STRLEN len|U32 utf8
Creates a new SV and copies a string (which may contain C<NUL> (C<\0>)
-characters) into it. If utf8 is true, calls
+characters) into it. If C<utf8> is true, calls
C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
=cut
/*
=for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len
-Reads into C<len> the offset from SvPVX back to the true start of the
+Reads into C<len> the offset from C<SvPVX> back to the true start of the
allocated buffer, which will be non-zero if C<sv_chop> has been used to
efficiently remove characters from start of the buffer. Implemented as a
macro, which takes the address of C<len>, which must be of type C<STRLEN>.
#define SV_CONSTS_COUNT 35
/*
+ * Bodyless IVs and NVs!
+ *
+ * Since 5.9.2, we can avoid allocating a body for SVt_IV-type SVs.
+ * Since the larger IV-holding variants of SVs store their integer
+ * values in their respective bodies, the family of SvIV() accessor
+ * macros would naively have to branch on the SV type to find the
+ * integer value either in the HEAD or BODY. In order to avoid this
+ * expensive branch, a clever soul has deployed a great hack:
+ * We set up the SvANY pointer such that instead of pointing to a
+ * real body, it points into the memory before the location of the
+ * head. We compute this pointer such that the location of
+ * the integer member of the hypothetical body struct happens to
+ * be the same as the location of the integer member of the bodyless
+ * SV head. This now means that the SvIV() family of accessors can
+ * always read from the (hypothetical or real) body via SvANY.
+ *
+ * Since the 5.21 dev series, we employ the same trick for NVs
+ * if the architecture can support it (NVSIZE <= IVSIZE).
+ */
+
+/* The following two macros compute the necessary offsets for the above
+ * trick and store them in SvANY for SvIV() (and friends) to use. */
+
+#ifdef PERL_CORE
+# define SET_SVANY_FOR_BODYLESS_IV(sv) \
+ SvANY(sv) = (XPVIV*)((char*)&(sv->sv_u.svu_iv) \
+ - STRUCT_OFFSET(XPVIV, xiv_iv))
+
+# define SET_SVANY_FOR_BODYLESS_NV(sv) \
+ SvANY(sv) = (XPVNV*)((char*)&(sv->sv_u.svu_nv) \
+ - STRUCT_OFFSET(XPVNV, xnv_u.xnv_nv))
+#endif
+
+/*
* ex: set ts=8 sts=4 sw=4 et:
*/