This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl5337delta: note that stadtx was removed
[perl5.git] / sv.h
diff --git a/sv.h b/sv.h
index 01277af..ba701ed 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -13,9 +13,9 @@
 #endif
 
 /*
-=head1 SV Flags
+=for apidoc_section $SV_flags
 
-=for apidoc AmU||svtype
+=for apidoc Ay||svtype
 An enum of flags for Perl types.  These are found in the file F<sv.h>
 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
 
@@ -72,52 +72,52 @@ 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
+=for apidoc AmnU||SVt_NULL
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_IV
+=for apidoc AmnU||SVt_IV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_NV
+=for apidoc AmnU||SVt_NV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PV
+=for apidoc AmnU||SVt_PV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVIV
+=for apidoc AmnU||SVt_PVIV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVNV
+=for apidoc AmnU||SVt_PVNV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVMG
+=for apidoc AmnU||SVt_PVMG
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_INVLIST
-Type flag for scalars.  See L</svtype>.
+=for apidoc CmnU||SVt_INVLIST
+Type flag for scalars.  See L<perlapi/svtype>.
 
-=for apidoc AmU||SVt_REGEXP
+=for apidoc AmnU||SVt_REGEXP
 Type flag for regular expressions.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVGV
+=for apidoc AmnU||SVt_PVGV
 Type flag for typeglobs.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVLV
+=for apidoc AmnU||SVt_PVLV
 Type flag for scalars.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVAV
+=for apidoc AmnU||SVt_PVAV
 Type flag for arrays.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVHV
+=for apidoc AmnU||SVt_PVHV
 Type flag for hashes.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVCV
+=for apidoc AmnU||SVt_PVCV
 Type flag for subroutines.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVFM
+=for apidoc AmnU||SVt_PVFM
 Type flag for formats.  See L</svtype>.
 
-=for apidoc AmU||SVt_PVIO
+=for apidoc AmnU||SVt_PVIO
 Type flag for I/O objects.  See L</svtype>.
 
 =cut
@@ -149,20 +149,24 @@ typedef enum {
        SVt_PVCV,       /* 13 */
        SVt_PVFM,       /* 14 */
        SVt_PVIO,       /* 15 */
+                        /* 16-31: Unused, though one should be reserved for a
+                         * freed sv, if the other 3 bits below the flags ones
+                         * get allocated */
        SVt_LAST        /* keep last in enum. used to size arrays */
 } svtype;
 
 /* *** any alterations to the SV types above need to be reflected in
  * SVt_MASK and the various PL_valid_types_* tables.  As of this writing those
  * tables are in perl.h.  There are also two affected names tables in dump.c,
- * one in B.xs, and 'bodies_by_type[]' in sv.c */
+ * one in B.xs, and 'bodies_by_type[]' in sv.c.
+ *
+ * The bits that match 0xe0 are CURRENTLY UNUSED
+ * The bits above that are for flags, like SVf_IOK */
 
-#define SVt_MASK 0x  /* smallest bitmask that covers all types */
+#define SVt_MASK 0x1f  /* 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:  */
@@ -207,7 +211,6 @@ typedef struct hek HEK;
        UV      svu_uv;                 \
        _NV_BODYLESS_UNION              \
        SV*     svu_rv;         /* pointer to another SV */             \
-       struct regexp* svu_rx;          \
        SV**    svu_array;              \
        HE**    svu_hash;               \
        GP*     svu_gp;                 \
@@ -262,63 +265,66 @@ struct p5rx {
     _SV_HEAD_UNION;
 };
 
+struct invlist {
+    _SV_HEAD(XINVLIST*);       /* pointer to xpvinvlist body */
+    _SV_HEAD_UNION;
+};
+
 #undef _SV_HEAD
 #undef _SV_HEAD_UNION          /* ensure no pollution */
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section $SV
 
 =for apidoc Am|U32|SvREFCNT|SV* sv
 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.
+=for apidoc SvREFCNT_inc
+=for apidoc_item SvREFCNT_inc_NN
+=for apidoc_item SvREFCNT_inc_void
+=for apidoc_item |void|SvREFCNT_inc_void_NN|SV* sv
+=for apidoc_item |SV*|SvREFCNT_inc_simple|SV* sv
+=for apidoc_item |SV*|SvREFCNT_inc_simple_NN|SV* sv
+=for apidoc_item |void|SvREFCNT_inc_simple_void|SV* sv
+=for apidoc_item |void|SvREFCNT_inc_simple_void_NN|SV* sv
+
+These all increment the reference count of the given SV.
+The ones without C<void> in their names return the SV.
 
-All of the following C<SvREFCNT_inc>* macros are optimized versions of
-C<SvREFCNT_inc>, and can be replaced with C<SvREFCNT_inc>.
+C<SvREFCNT_inc> is the base operation; the rest are optimizations if various
+input constraints are known to be true; hence, all can be replaced with
+C<SvREFCNT_inc>.
 
-=for apidoc Am|SV*|SvREFCNT_inc_NN|SV* sv
-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.
+C<SvREFCNT_inc_NN> 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 C<SvREFCNT_inc>, but can only be used if you don't need the
+C<SvREFCNT_inc_void> 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 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.
+C<SvREFCNT_inc_void_NN> can only be used if you both 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 C<SvREFCNT_inc>, but can only be used with expressions without side
+C<SvREFCNT_inc_simple> 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 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.
+C<SvREFCNT_inc_simple_NN> can only be used with expressions without side
+effects and you know C<sv> is not C<NULL>.  Since we don't have to store a
+temporary value, nor check for NULLness, it's faster and smaller.
 
-=for apidoc Am|void|SvREFCNT_inc_simple_void|SV* sv
-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.
+C<SvREFCNT_inc_simple_void> can only be used with expressions without side
+effects and you don't need the return value.
+
+C<SvREFCNT_inc_simple_void_NN> can only be used with expressions without side
+effects, you don't need the return value, and you know C<sv> is not C<NULL>.
 
-=for apidoc Am|void|SvREFCNT_inc_simple_void_NN|SV* sv
-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 SvREFCNT_dec
+=for apidoc_item SvREFCNT_dec_NN
 
-=for apidoc Am|void|SvREFCNT_dec|SV* sv
-Decrements the reference count of the given SV.  C<sv> may be C<NULL>.
+These decrement the reference count of the given SV.
 
-=for apidoc Am|void|SvREFCNT_dec_NN|SV* sv
-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.
+C<SvREFCNT_dec_NN> may only be used when C<sv> is known to not be C<NULL>.
 
 =for apidoc Am|svtype|SvTYPE|SV* sv
 Returns the type of the SV.  See C<L</svtype>>.
@@ -334,10 +340,10 @@ perform the upgrade if necessary.  See C<L</svtype>>.
 #define SvFLAGS(sv)    (sv)->sv_flags
 #define SvREFCNT(sv)   (sv)->sv_refcnt
 
-#define SvREFCNT_inc(sv)               S_SvREFCNT_inc(MUTABLE_SV(sv))
+#define SvREFCNT_inc(sv)               Perl_SvREFCNT_inc(MUTABLE_SV(sv))
 #define SvREFCNT_inc_simple(sv)                SvREFCNT_inc(sv)
-#define SvREFCNT_inc_NN(sv)            S_SvREFCNT_inc_NN(MUTABLE_SV(sv))
-#define SvREFCNT_inc_void(sv)          S_SvREFCNT_inc_void(MUTABLE_SV(sv))
+#define SvREFCNT_inc_NN(sv)            Perl_SvREFCNT_inc_NN(MUTABLE_SV(sv))
+#define SvREFCNT_inc_void(sv)          Perl_SvREFCNT_inc_void(MUTABLE_SV(sv))
 
 /* These guys don't need the curly blocks */
 #define SvREFCNT_inc_simple_void(sv)   STMT_START { if (sv) SvREFCNT(sv)++; } STMT_END
@@ -345,8 +351,8 @@ perform the upgrade if necessary.  See C<L</svtype>>.
 #define SvREFCNT_inc_void_NN(sv)       (void)(++SvREFCNT(MUTABLE_SV(sv)))
 #define SvREFCNT_inc_simple_void_NN(sv)        (void)(++SvREFCNT(MUTABLE_SV(sv)))
 
-#define SvREFCNT_dec(sv)       S_SvREFCNT_dec(aTHX_ MUTABLE_SV(sv))
-#define SvREFCNT_dec_NN(sv)    S_SvREFCNT_dec_NN(aTHX_ MUTABLE_SV(sv))
+#define SvREFCNT_dec(sv)       Perl_SvREFCNT_dec(aTHX_ MUTABLE_SV(sv))
+#define SvREFCNT_dec_NN(sv)    Perl_SvREFCNT_dec_NN(aTHX_ MUTABLE_SV(sv))
 
 #define SVTYPEMASK     0xff
 #define SvTYPE(sv)     ((svtype)((sv)->sv_flags & SVTYPEMASK))
@@ -376,6 +382,15 @@ perform the upgrade if necessary.  See C<L</svtype>>.
                                       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;
@@ -392,7 +407,12 @@ perform the upgrade if necessary.  See C<L</svtype>>.
                                          refers to an eval or once only
                                          [CvEVAL(cv), CvSPECIAL(cv)]
                                        3: HV: informally reserved by DAPM
-                                          for vtables */
+                                          for vtables
+                                       4: Together with other flags (or
+                                           lack thereof) indicates a regex,
+                                           including PVLV-as-regex. See
+                                           isREGEXP().
+                                       */
 #define SVf_OOK                0x02000000  /* has valid offset value. For a PVHV this
                                       means that a hv_aux struct is present
                                       after the main array */
@@ -415,7 +435,12 @@ perform the upgrade if necessary.  See C<L</svtype>>.
 
 #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 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) */
@@ -437,27 +462,10 @@ perform the upgrade if necessary.  See C<L</svtype>>.
 /* 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
-   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 */
@@ -465,8 +473,6 @@ perform the upgrade if necessary.  See C<L</svtype>>.
 #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  /* string has a fake "\n" appended */
 /* RV upwards. However, SVf_ROK and SVp_IOK are exclusive  */
 #define SVprv_WEAKREF   0x80000000  /* Weak reference */
 /* pad name vars only */
@@ -477,7 +483,7 @@ perform the upgrade if necessary.  See C<L</svtype>>.
     STRLEN     xpv_cur;        /* length of svu_pv as a C string */    \
     union {                                                            \
        STRLEN  xpvlenu_len;    /* allocated size */                    \
-       char *  xpvlenu_pv;     /* regexp string */                     \
+        struct regexp* xpvlenu_rx; /* regex when SV body is XPVLV */    \
     } xpv_len_u        
 
 #define xpv_len        xpv_len_u.xpvlenu_len
@@ -486,12 +492,15 @@ union _xnvu {
     NV     xnv_nv;             /* numeric value, if any */
     HV *    xgv_stash;
     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 {
@@ -542,7 +551,8 @@ struct xpvlv {
     SV*                xlv_targ;
     char       xlv_type;       /* k=keys .=pos x=substr v=vec /=join/re
                                 * y=alem/helem/iter t=tie T=tied HE */
-    char       xlv_flags;      /* 1 = negative offset  2 = negative len */
+    char       xlv_flags;      /* 1 = negative offset  2 = negative len
+                                   4 = out of range (vec) */
 };
 
 #define xlv_targoff xlv_targoff_u.xlvu_targoff
@@ -559,8 +569,8 @@ struct xpvinvlist {
                                    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;
@@ -695,12 +705,12 @@ 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 C<SvUOK> or C<SVIOK>.
+range of both an IV and a UV may 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 C<SvUOK> or C<SVIOK>.
+range of both an IV and a UV may 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.
@@ -737,7 +747,7 @@ Returns a boolean indicating whether the SV contains a v-string.
 =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 C<SvPV>.  When C<SvOOK> is true, then the start of the
+beginning of a C<L</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.
@@ -762,19 +772,34 @@ Only use when you are sure C<SvIOK> is true.  See also C<L</SvIV>>.
 Returns the raw value in the SV's UV slot, without checks or conversions.
 Only use when you are sure C<SvIOK> is true.  See also C<L</SvUV>>.
 
+=for apidoc AmD|UV|SvUVXx|SV* sv
+This is an unnecessary synonym for L</SvUVX>
+
 =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 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
+=for apidoc_item |char*|SvPVXx|SV* sv
+=for apidoc_item |const char*|SvPVX_const|SV* sv
+=for apidoc_item |char*|SvPVX_mutable|SV* sv
+
+These return 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 these unless the SV's
 type >= C<SVt_PV>.
 
-This is also used to store the name of an autoloaded subroutine in an XS
+These are also used to store the name of an autoloaded subroutine in an XS
 AUTOLOAD routine.  See L<perlguts/Autoloading with XSUBs>.
 
+C<SvPVXx> is identical to C<SvPVX>.
+
+C<SvPVX_mutable> is merely a synonym for C<SvPVX>, but its name emphasizes that
+the string is modifiable by the caller.
+
+C<SvPVX_const> differs in that the return value has been cast so that the
+compiler will complain if you were to try to modify the contents of the string,
+(unless you cast away const yourself).
+
 =for apidoc Am|STRLEN|SvCUR|SV* sv
 Returns the length of the string which is in the SV.  See C<L</SvLEN>>.
 
@@ -814,8 +839,8 @@ 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 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.
+modification is safe. Then finally, if it is not a COW, call
+C<L</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 C<sv> to val.  See C<L</SvIV_set>>.
@@ -847,7 +872,7 @@ Set the size of the string buffer for the SV. See C<L</SvLEN>>.
 #define assert_not_ROK(sv)     assert_(!SvROK(sv) || !SvRV(sv))
 #define assert_not_glob(sv)    assert_(!isGV_with_GP(sv))
 
-#define SvOK(sv)               (SvFLAGS(sv) & SVf_OK || isREGEXP(sv))
+#define SvOK(sv)               (SvFLAGS(sv) & SVf_OK)
 #define SvOK_off(sv)           (assert_not_ROK(sv) assert_not_glob(sv) \
                                 SvFLAGS(sv) &= ~(SVf_OK|               \
                                                  SVf_IVisUV|SVf_UTF8), \
@@ -897,7 +922,7 @@ Set the size of the string buffer for the SV. See C<L</SvLEN>>.
 =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 C<SvPV()> or one of its variants, in
+You should use this I<after> a call to C<L</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>>
@@ -939,12 +964,28 @@ in gv.h: */
 
 #define SvVOK(sv)              (SvMAGICAL(sv)                          \
                                 && mg_find(sv,PERL_MAGIC_vstring))
-/* returns the vstring magic, if any */
+/*
+=for apidoc Am|MAGIC*|SvVSTRING_mg|SV * sv
+
+Returns the vstring magic, or NULL if none
+
+=cut
+*/
 #define SvVSTRING_mg(sv)       (SvMAGICAL(sv) \
                                 ? mg_find(sv,PERL_MAGIC_vstring) : NULL)
 
 #define SvOOK(sv)              (SvFLAGS(sv) & SVf_OOK)
 #define SvOOK_on(sv)           (SvFLAGS(sv) |= SVf_OOK)
+
+
+/*
+=for apidoc Am|void|SvOOK_off|SV * sv
+
+Remove any string offset.
+
+=cut
+*/
+
 #define SvOOK_off(sv)          ((void)(SvOOK(sv) && (sv_backoff(sv),0)))
 
 #define SvFAKE(sv)             (SvFLAGS(sv) & SVf_FAKE)
@@ -1074,8 +1115,8 @@ C<sv_force_normal> does nothing.
 
 #define SvPADTMP_on(sv)                (SvFLAGS(sv) |= SVs_PADTMP)
 #define SvPADTMP_off(sv)       (SvFLAGS(sv) &= ~SVs_PADTMP)
-#define SvPADSTALE_on(sv)      S_SvPADSTALE_on(MUTABLE_SV(sv))
-#define SvPADSTALE_off(sv)     S_SvPADSTALE_off(MUTABLE_SV(sv))
+#define SvPADSTALE_on(sv)      Perl_SvPADSTALE_on(MUTABLE_SV(sv))
+#define SvPADSTALE_off(sv)     Perl_SvPADSTALE_off(MUTABLE_SV(sv))
 
 #define SvTEMP(sv)             (SvFLAGS(sv) & SVs_TEMP)
 #define SvTEMP_on(sv)          (SvFLAGS(sv) |= SVs_TEMP)
@@ -1088,7 +1129,7 @@ C<sv_force_normal> does nothing.
 /*
 =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().
+Exposed 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
@@ -1120,44 +1161,28 @@ object type. Exposed to perl code via Internals::SvREADONLY().
 #  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); \
-                               })
 
+#if defined (DEBUGGING) && defined(PERL_USE_GCC_BRACE_GROUPS)
 #  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)
 
@@ -1181,11 +1206,15 @@ object type. Exposed to perl code via Internals::SvREADONLY().
 
 #  define SvMAGIC(sv)  (0 + *(assert_(SvTYPE(sv) >= SVt_PVMG) &((XPVMG*)  SvANY(sv))->xmg_u.xmg_magic))
 #  define SvSTASH(sv)  (0 + *(assert_(SvTYPE(sv) >= SVt_PVMG) &((XPVMG*)  SvANY(sv))->xmg_stash))
-#else
+#else   /* Below is not PERL_DEBUG_COW */
+# ifdef PERL_CORE
+#  define SvLEN(sv) (0 + ((XPV*) SvANY(sv))->xpv_len)
+# else
 #  define SvLEN(sv) ((XPV*) SvANY(sv))->xpv_len
+# endif
 #  define SvEND(sv) ((sv)->sv_u.svu_pv + ((XPV*)SvANY(sv))->xpv_cur)
 
-#  if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
+#  if defined (DEBUGGING) && defined(PERL_USE_GCC_BRACE_GROUPS)
 /* These get expanded inside other macros that already use a variable _sv  */
 #    define SvPVX(sv)                                                  \
        (*({ SV *const _svpvx = MUTABLE_SV(sv);                         \
@@ -1195,15 +1224,25 @@ object type. Exposed to perl code via Internals::SvREADONLY().
                     && !(IoFLAGS(_svpvx) & IOf_FAKE_DIRP)));           \
            &((_svpvx)->sv_u.svu_pv);                                   \
         }))
+#   ifdef PERL_CORE
+#    define SvCUR(sv)                                                  \
+       ({ const SV *const _svcur = (const SV *)(sv);                   \
+           assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK]);      \
+           assert(!isGV_with_GP(_svcur));                              \
+           assert(!(SvTYPE(_svcur) == SVt_PVIO                         \
+                    && !(IoFLAGS(_svcur) & IOf_FAKE_DIRP)));           \
+           (((XPV*) MUTABLE_PTR(SvANY(_svcur)))->xpv_cur);             \
+        })
+#   else
 #    define SvCUR(sv)                                                  \
        (*({ const SV *const _svcur = (const SV *)(sv);                 \
-           assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK]        \
-               || SvTYPE(_svcur) == SVt_REGEXP);                       \
+           assert(PL_valid_types_PVX[SvTYPE(_svcur) & SVt_MASK]);      \
            assert(!isGV_with_GP(_svcur));                              \
            assert(!(SvTYPE(_svcur) == SVt_PVIO                         \
                     && !(IoFLAGS(_svcur) & IOf_FAKE_DIRP)));           \
            &(((XPV*) MUTABLE_PTR(SvANY(_svcur)))->xpv_cur);            \
         }))
+#   endif
 #    define SvIVX(sv)                                                  \
        (*({ const SV *const _svivx = (const SV *)(sv);                 \
            assert(PL_valid_types_IVX[SvTYPE(_svivx) & SVt_MASK]);      \
@@ -1248,7 +1287,7 @@ object type. Exposed to perl code via Internals::SvREADONLY().
            assert(SvTYPE(_svstash) >= SVt_PVMG);                       \
            &(((XPVMG*) MUTABLE_PTR(SvANY(_svstash)))->xmg_stash);      \
          }))
-#  else
+#  else     /* Below is not DEBUGGING or can't use brace groups */
 #    define SvPVX(sv) ((sv)->sv_u.svu_pv)
 #    define SvCUR(sv) ((XPV*) SvANY(sv))->xpv_cur
 #    define SvIVX(sv) ((XPVIV*) SvANY(sv))->xiv_iv
@@ -1263,7 +1302,7 @@ object type. Exposed to perl code via Internals::SvREADONLY().
 
 #ifndef PERL_POISON
 /* Given that these two are new, there can't be any existing code using them
- *  as LVALUEs  */
+ *  as LVALUEs, so prevent that from happening  */
 #  define SvPVX_mutable(sv)    (0 + (sv)->sv_u.svu_pv)
 #  define SvPVX_const(sv)      ((const char*)(0 + (sv)->sv_u.svu_pv))
 #else
@@ -1328,8 +1367,7 @@ object type. Exposed to perl code via Internals::SvREADONLY().
                 (((XPVMG*)  SvANY(sv))->xmg_stash = (val)); } STMT_END
 #define SvCUR_set(sv, val) \
        STMT_START { \
-               assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK]        \
-                       || SvTYPE(sv) == SVt_REGEXP);   \
+               assert(PL_valid_types_PVX[SvTYPE(sv) & SVt_MASK]);      \
                assert(!isGV_with_GP(sv));              \
                assert(!(SvTYPE(sv) == SVt_PVIO         \
                     && !(IoFLAGS(sv) & IOf_FAKE_DIRP))); \
@@ -1345,6 +1383,17 @@ object type. Exposed to perl code via Internals::SvREADONLY().
        STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
                SvCUR_set(sv, (val) - SvPVX(sv)); } STMT_END
 
+/*
+=for apidoc Am|void|SvPV_renew|SV* sv|STRLEN len
+Low level micro optimization of C<L</SvGROW>>.  It is generally better to use
+C<SvGROW> instead.  This is because C<SvPV_renew> ignores potential issues that
+C<SvGROW> handles.  C<sv> needs to have a real C<PV> that is unencombered by
+things like COW.  Using C<SV_CHECK_THINKFIRST> or
+C<SV_CHECK_THINKFIRST_COW_DROP> before calling this should clean it up, but
+why not just use C<SvGROW> if you're not sure about the provenance?
+
+=cut
+*/
 #define SvPV_renew(sv,n) \
        STMT_START { SvLEN_set(sv, n); \
                SvPV_set((sv), (MEM_WRAP_CHECK_(n,char)                 \
@@ -1357,6 +1406,14 @@ object type. Exposed to perl code via Internals::SvREADONLY().
                   SvPV_renew(sv, _lEnGtH); \
                 } STMT_END
 
+/*
+=for apidoc Am|void|SvPV_free|SV * sv
+
+Frees the PV buffer in C<sv>, leaving things in a precarious state, so should
+only be used as part of a larger operation
+
+=cut
+*/
 #define SvPV_free(sv)                                                  \
     STMT_START {                                                       \
                     assert(SvTYPE(sv) >= SVt_PV);                      \
@@ -1391,7 +1448,7 @@ object type. Exposed to perl code via Internals::SvREADONLY().
 #  define BmFLAGS(sv)          (SvTAIL(sv) ? FBMcf_TAIL : 0)
 #endif
 
-#if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
+#if defined (DEBUGGING) && defined(PERL_USE_GCC_BRACE_GROUPS)
 #  define BmUSEFUL(sv)                                                 \
        (*({ SV *const _bmuseful = MUTABLE_SV(sv);                      \
            assert(SvTYPE(_bmuseful) >= SVt_PVIV);                      \
@@ -1418,6 +1475,10 @@ object type. Exposed to perl code via Internals::SvREADONLY().
 #define LvTARGLEN(sv)  ((XPVLV*)  SvANY(sv))->xlv_targlen
 #define LvFLAGS(sv)    ((XPVLV*)  SvANY(sv))->xlv_flags
 
+#define LVf_NEG_OFF      0x1
+#define LVf_NEG_LEN      0x2
+#define LVf_OUT_OF_RANGE 0x4
+
 #define IoIFP(sv)      (sv)->sv_u.svu_fp
 #define IoOFP(sv)      ((XPVIO*)  SvANY(sv))->xio_ofp
 #define IoDIRP(sv)     ((XPVIO*)  SvANY(sv))->xio_dirp
@@ -1492,9 +1553,23 @@ attention to precisely which outputs are influenced by which inputs.
 
 /*
 =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 need force if you are
-going to update the C<SvPVX> directly.  Processes get magic.
+=for apidoc_item ||SvPV_force_nolen|SV* sv
+=for apidoc_item ||SvPVx_force|SV* sv|STRLEN len
+=for apidoc_item ||SvPV_force_nomg|SV* sv|STRLEN len
+=for apidoc_item ||SvPV_force_nomg_nolen|SV * sv
+=for apidoc_item ||SvPV_force_mutable|SV * sv|STRLEN len
+=for apidoc_item ||SvPV_force_flags|SV * sv|STRLEN len|U32 flags
+=for apidoc_item ||SvPV_force_flags_nolen|SV * sv|U32 flags
+=for apidoc_item ||SvPV_force_flags_mutable|SV * sv|STRLEN len|U32 flags
+=for apidoc_item ||SvPVbyte_force
+=for apidoc_item ||SvPVbytex_force
+=for apidoc_item ||SvPVutf8_force
+=for apidoc_item ||SvPVutf8x_force
+
+These are like C<L</SvPV>>, returning the string in the SV, but will force the
+SV into containing a string (C<L</SvPOK>>), and only a string
+(C<L</SvPOK_only>>), by hook or by crook.  You need to use one of these
+C<force> routines if you are going to update the C<L</SvPVX>> directly.
 
 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
@@ -1502,88 +1577,196 @@ 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_force>, but doesn't process get magic.
+The differences between the forms are:
+
+The forms with C<flags> in their names allow you to use the C<flags> parameter
+to specify to perform 'get' magic (by setting the C<SV_GMAGIC> flag) or to skip
+'get' magic (by clearing it).  The other forms do perform 'get' magic, except
+for the ones with C<nomg> in their names, which skip 'get' magic.
+
+The forms that take a C<len> parameter will set that variable to the byte
+length of the resultant string (these are macros, so don't use C<&len>).
+
+The forms with C<nolen> in their names indicate they don't have a C<len>
+parameter.  They should be used only when it is known that the PV is a C
+string, terminated by a NUL byte, and without intermediate NUL characters; or
+when you don't care about its length.
+
+The forms with C<mutable> in their names are effectively the same as those without,
+but the name emphasizes that the string is modifiable by the caller, which it is
+in all the forms.
+
+C<SvPVutf8_force> is like C<SvPV_force>, but converts C<sv> to UTF-8 first if
+not already UTF-8.
+
+C<SvPVutf8x_force> is like C<SvPVutf8_force>, but guarantees to evaluate C<sv>
+only once; use the more efficient C<SvPVutf8_force> otherwise.
+
+C<SvPVbyte_force> is like C<SvPV_force>, but converts C<sv> to byte
+representation first if currently encoded as UTF-8.  If the SV cannot be
+downgraded from UTF-8, this croaks.
+
+C<SvPVbytex_force> is like C<SvPVbyte_force>, but guarantees to evaluate C<sv>
+only once; use the more efficient C<SvPVbyte_force> otherwise.
 
 =for apidoc Am|char*|SvPV|SV* sv|STRLEN len
-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 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 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 C<SvPVX> field to
-be valid (for example, if you intend to write to it), then see
-C<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
-more efficient C<SvPV>.
-
-=for apidoc Am|char*|SvPV_nomg|SV* sv|STRLEN len
-Like C<SvPV> but doesn't process magic.
-
-=for apidoc Am|char*|SvPV_nolen|SV* sv
-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_item |char*|SvPVx|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPV_nomg|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPV_nolen|SV* sv
+=for apidoc_item |char*|SvPVx_nolen|SV* sv
+=for apidoc_item |char*|SvPV_nomg_nolen|SV* sv
+=for apidoc_item |char*|SvPV_mutable|SV* sv|STRLEN len
+=for apidoc_item |const char*|SvPV_const|SV* sv|STRLEN len
+=for apidoc_item |const char*|SvPVx_const|SV* sv|STRLEN len
+=for apidoc_item |const char*|SvPV_nolen_const|SV* sv
+=for apidoc_item |const char*|SvPVx_nolen_const|SV* sv
+=for apidoc_item |const char*|SvPV_nomg_const|SV* sv|STRLEN len
+=for apidoc_item |const char*|SvPV_nomg_const_nolen|SV* sv
+=for apidoc_item |char *|SvPV_flags|SV * sv|STRLEN len|U32 flags
+=for apidoc_item |const char *|SvPV_flags_const|SV * sv|STRLEN len|U32 flags
+=for apidoc_item |char *|SvPV_flags_mutable|SV * sv|STRLEN len|U32 flags
+=for apidoc_item |char*|SvPVbyte|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVbyte_nomg|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVbyte_nolen|SV* sv
+=for apidoc_item |char*|SvPVbytex_nolen|SV* sv
+=for apidoc_item |char*|SvPVbytex|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVbyte_or_null|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVbyte_or_null_nomg|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVutf8|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVutf8x|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVutf8_nomg|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVutf8_nolen|SV* sv
+=for apidoc_item |char*|SvPVutf8_or_null|SV* sv|STRLEN len
+=for apidoc_item |char*|SvPVutf8_or_null_nomg|SV* sv|STRLEN len
+
+All these return a pointer to the string in C<sv>, or a stringified form of
+C<sv> if it does not contain a string.  The SV may cache the stringified
+version becoming C<SvPOK>.
+
+This is a very basic and common operation, so there are lots of slightly
+different versions of it.
+
+Note that there is no guarantee that the return value of C<SvPV(sv)>, for
+example, is equal to C<SvPVX(sv)>, or that C<SvPVX(sv)> contains valid data, or
+that successive calls to C<SvPV(sv)> (or another of these forms) 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
+C<SvPVX> field to be valid (for example, if you intend to write to it), then
+see C<L</SvPV_force>>.
+
+The differences between the forms are:
+
+The forms with C<flags> in their names allow you to use the C<flags> parameter
+to specify to process 'get' magic (by setting the C<SV_GMAGIC> flag) or to skip
+'get' magic (by clearing it).  The other forms process 'get' magic, except for
+the ones with C<nomg> in their names, which skip 'get' magic.
+
+The forms that take a C<len> parameter will set that variable to the byte
+length of the resultant string (these are macros, so don't use C<&len>).
+
+The forms with C<nolen> in their names indicate they don't have a C<len>
+parameter.  They should be used only when it is known that the PV is a C
+string, terminated by a NUL byte, and without intermediate NUL characters; or
+when you don't care about its length.
+
+The forms with C<const> in their names return S<C<const char *>> so that the
+compiler will hopefully complain if you were to try to modify the contents of
+the string (unless you cast away const yourself).
+
+The other forms return a mutable pointer so that the string is modifiable by
+the caller; this is emphasized for the ones with C<mutable> in their names.
+
+The forms whose name ends in C<x> are the same as the corresponding form
+without the C<x>, but the C<x> form is guaranteed to evaluate C<sv> exactly
+once, with a slight loss of efficiency.  Use this if C<sv> is an expression
+with side effects.
+
+C<SvPVutf8> is like C<SvPV>, but converts C<sv> to UTF-8 first if not already
+UTF-8.  Similiarly, the other forms with C<utf8> in their names correspond to
+their respective forms without.
+
+C<SvPVutf8_or_null> and C<SvPVutf8_or_null_nomg> don't have corresponding
+non-C<utf8> forms.  Instead they are like C<SvPVutf8_nomg>, but when C<sv> is
+undef, they return C<NULL>.
+
+C<SvPVbyte> is like C<SvPV>, but converts C<sv> to byte representation first if
+currently encoded as UTF-8.  If C<sv> cannot be downgraded from UTF-8, it
+croaks.  Similiarly, the other forms with C<byte> in their names correspond to
+their respective forms without.
+
+C<SvPVbyte_or_null> doesn't have a corresponding non-C<byte> form.  Instead it
+is like C<SvPVbyte>, but when C<sv> is undef, it returns C<NULL>.
 
 =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 C<sv> only once.
+=for apidoc_item SvIVx
+=for apidoc_item SvIV_nomg
 
-=for apidoc Am|IV|SvIV_nomg|SV* sv
-Like C<SvIV> but doesn't process magic.
+These coerce the given SV to IV and return it.  The returned value in many
+circumstances will get stored in C<sv>'s IV slot, but not in all cases.  (Use
+C<L</sv_setiv>> to make sure it does).
 
-=for apidoc Am|IV|SvIVx|SV* sv
-Coerces the given SV to an integer and 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<SvIV>.
+C<SvIVx> is different from the others in that it is guaranteed to evaluate
+C<sv> exactly once; the others may evaluate it multiple times.  Only use this
+form if C<sv> is an expression with side effects, otherwise use the more
+efficient C<SvIV>.
+
+C<SvIV_nomg> is the same as C<SvIV>, but does not perform 'get' 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 C<sv> only once.
+=for apidoc_item SvNVx
+=for apidoc_item SvNV_nomg
+
+These coerce the given SV to NV and return it.  The returned value in many
+circumstances will get stored in C<sv>'s NV slot, but not in all cases.  (Use
+C<L</sv_setnv>> to make sure it does).
 
-=for apidoc Am|NV|SvNV_nomg|SV* sv
-Like C<SvNV> but doesn't process magic.
+C<SvNVx> is different from the others in that it is guaranteed to evaluate
+C<sv> exactly once; the others may evaluate it multiple times.  Only use this
+form if C<sv> is an expression with side effects, otherwise use the more
+efficient C<SvNV>.
 
-=for apidoc Am|NV|SvNVx|SV* sv
-Coerces the given SV to a double and 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<SvNV>.
+C<SvNV_nomg> is the same as C<SvNV>, but does not perform 'get' 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 C<sv> only once.
+=for apidoc_item SvUVx
+=for apidoc_item SvUV_nomg
+
+These coerce the given SV to UV and return it.  The returned value in many
+circumstances will get stored in C<sv>'s UV slot, but not in all cases.  (Use
+C<L</sv_setuv>> to make sure it does).
+
+C<SvUVx> is different from the others in that it is guaranteed to evaluate
+C<sv> exactly once; the others may evaluate it multiple times.  Only use this
+form if C<sv> is an expression with side effects, otherwise use the more
+efficient C<SvUV>.
+
+C<SvUV_nomg> is the same as C<SvUV>, but does not perform 'get' magic.
+
+=for apidoc SvTRUE
+=for apidoc_item SvTRUEx
+=for apidoc_item SvTRUE_nomg
+=for apidoc_item SvTRUE_NN
+=for apidoc_item SvTRUE_nomg_NN
 
-=for apidoc Am|UV|SvUV_nomg|SV* sv
-Like C<SvUV> but doesn't process magic.
+These return a boolean indicating whether Perl would evaluate the SV as true or
+false.  See C<L</SvOK>> for a defined/undefined test.
 
-=for apidoc Am|UV|SvUVx|SV* sv
-Coerces the given SV to an unsigned integer and
-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>.
+As of Perl 5.32, all are guaranteed to evaluate C<sv> only once.  Prior to that
+release, only C<SvTRUEx> guaranteed single evaluation; now C<SvTRUEx> is
+identical to C<SvTRUE>.
 
-=for apidoc Am|bool|SvTRUE|SV* sv
-Returns a boolean indicating whether Perl would evaluate the SV as true or
-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).
+C<SvTRUE_nomg> and C<TRUE_nomg_NN> do not perform 'get' magic; the others do
+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 C<L</SvOK>> for a defined/undefined test.  Does not handle 'get' magic.
+C<SvTRUE_NN> is like C<L</SvTRUE>>, but C<sv> is assumed to be
+non-null (NN).  If there is a possibility that it is NULL, use plain
+C<SvTRUE>.
+
+C<SvTRUE_nomg_NN> is like C<L</SvTRUE_nomg>>, but C<sv> is assumed to be
+non-null (NN).  If there is a possibility that it is NULL, use plain
+C<SvTRUE_nomg>.
 
 =for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len
 Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
@@ -1591,37 +1774,38 @@ 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 C<sv> to UTF-8 first if necessary.
 
+=for apidoc Am|char*|SvPVutf8_nomg|SV* sv|STRLEN len
+Like C<SvPVutf8>, but does not process get magic.
+
+=for apidoc Am|char*|SvPVutf8_or_null|SV* sv|STRLEN len
+Like C<SvPVutf8>, but when C<sv> is undef, returns C<NULL>.
+
+=for apidoc Am|char*|SvPVutf8_or_null_nomg|SV* sv|STRLEN len
+Like C<SvPVutf8_or_null>, but does not process get magic.
+
 =for apidoc Am|char*|SvPVutf8_nolen|SV* sv
 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 C<sv> to byte representation first if necessary.
+Like C<SvPV_force>, but converts C<sv> to byte representation first if
+necessary.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
-Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.  If
+the SV cannot be downgraded from UTF-8, this croaks.
 
-=for apidoc Am|char*|SvPVbyte_nolen|SV* sv
-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 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*|SvPVbyte_nomg|SV* sv|STRLEN len
+Like C<SvPVbyte>, but does not process get magic.
 
-=for apidoc Am|char*|SvPVutf8x|SV* sv|STRLEN len
-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*|SvPVbyte_or_null|SV* sv|STRLEN len
+Like C<SvPVbyte>, but when C<sv> is undef, returns C<NULL>.
 
-=for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len
-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*|SvPVbyte_or_null_nomg|SV* sv|STRLEN len
+Like C<SvPVbyte_or_null>, but does not process get magic.
 
-=for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len
-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|char*|SvPVbyte_nolen|SV* sv
+Like C<SvPV_nolen>, but converts C<sv> to byte representation first if
+necessary.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|U32|SvIsCOW|SV* sv
 Returns a U32 value indicating whether the SV is Copy-On-Write (either shared
@@ -1632,22 +1816,6 @@ COW).
 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
 scalar.
 
-=for apidoc Am|void|sv_catpvn_nomg|SV* sv|const char* ptr|STRLEN len
-Like C<sv_catpvn> but doesn't process magic.
-
-=for apidoc Am|void|sv_catpv_nomg|SV* sv|const char* ptr
-Like C<sv_catpv> but doesn't process magic.
-
-=for apidoc Am|void|sv_setsv_nomg|SV* dsv|SV* ssv
-Like C<sv_setsv> but doesn't process magic.
-
-=for apidoc Am|void|sv_catsv_nomg|SV* dsv|SV* ssv
-Like C<sv_catsv> but doesn't process magic.
-
-=for apidoc Amdb|STRLEN|sv_utf8_upgrade_nomg|NN SV *sv
-
-Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
-
 =cut
 */
 
@@ -1657,50 +1825,50 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 #define SvNV(sv) (SvNOK_nog(sv) ? SvNVX(sv) : sv_2nv(sv))
 
 #define SvIV_nomg(sv) (SvIOK(sv) ? SvIVX(sv) : sv_2iv_flags(sv, 0))
-#define SvUV_nomg(sv) (SvIOK(sv) ? SvUVX(sv) : sv_2uv_flags(sv, 0))
+#define SvUV_nomg(sv) (SvUOK(sv) ? SvUVX(sv) : sv_2uv_flags(sv, 0))
 #define SvNV_nomg(sv) (SvNOK(sv) ? SvNVX(sv) : sv_2nv_flags(sv, 0))
 
 /* ----*/
 
-#define SvPV(sv, lp)         SvPV_flags(sv, lp, SV_GMAGIC)
-#define SvPV_const(sv, lp)   SvPV_flags_const(sv, lp, SV_GMAGIC)
-#define SvPV_mutable(sv, lp) SvPV_flags_mutable(sv, lp, SV_GMAGIC)
+#define SvPV(sv, len)         SvPV_flags(sv, len, SV_GMAGIC)
+#define SvPV_const(sv, len)   SvPV_flags_const(sv, len, SV_GMAGIC)
+#define SvPV_mutable(sv, len) SvPV_flags_mutable(sv, len, SV_GMAGIC)
 
-#define SvPV_flags(sv, lp, flags) \
+#define SvPV_flags(sv, len, flags) \
     (SvPOK_nog(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pv_flags(sv, &lp, flags))
-#define SvPV_flags_const(sv, lp, flags) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pv_flags(sv, &len, flags))
+#define SvPV_flags_const(sv, len, flags) \
     (SvPOK_nog(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX_const(sv)) : \
-     (const char*) sv_2pv_flags(sv, &lp, (flags|SV_CONST_RETURN)))
+     ? ((len = SvCUR(sv)), SvPVX_const(sv)) : \
+     (const char*) sv_2pv_flags(sv, &len, (flags|SV_CONST_RETURN)))
 #define SvPV_flags_const_nolen(sv, flags) \
     (SvPOK_nog(sv) \
      ? SvPVX_const(sv) : \
      (const char*) sv_2pv_flags(sv, 0, (flags|SV_CONST_RETURN)))
-#define SvPV_flags_mutable(sv, lp, flags) \
+#define SvPV_flags_mutable(sv, len, flags) \
     (SvPOK_nog(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX_mutable(sv)) : \
-     sv_2pv_flags(sv, &lp, (flags|SV_MUTABLE_RETURN)))
+     ? ((len = SvCUR(sv)), SvPVX_mutable(sv)) : \
+     sv_2pv_flags(sv, &len, (flags|SV_MUTABLE_RETURN)))
 
-#define SvPV_force(sv, lp) SvPV_force_flags(sv, lp, SV_GMAGIC)
+#define SvPV_force(sv, len) SvPV_force_flags(sv, len, SV_GMAGIC)
 #define SvPV_force_nolen(sv) SvPV_force_flags_nolen(sv, SV_GMAGIC)
-#define SvPV_force_mutable(sv, lp) SvPV_force_flags_mutable(sv, lp, SV_GMAGIC)
+#define SvPV_force_mutable(sv, len) SvPV_force_flags_mutable(sv, len, SV_GMAGIC)
 
-#define SvPV_force_nomg(sv, lp) SvPV_force_flags(sv, lp, 0)
+#define SvPV_force_nomg(sv, len) SvPV_force_flags(sv, len, 0)
 #define SvPV_force_nomg_nolen(sv) SvPV_force_flags_nolen(sv, 0)
 
-#define SvPV_force_flags(sv, lp, flags) \
+#define SvPV_force_flags(sv, len, flags) \
     (SvPOK_pure_nogthink(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvn_force_flags(sv, &lp, flags))
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_pvn_force_flags(sv, &len, flags))
 
 #define SvPV_force_flags_nolen(sv, flags) \
     (SvPOK_pure_nogthink(sv) \
      ? SvPVX(sv) : sv_pvn_force_flags(sv, 0, flags))
 
-#define SvPV_force_flags_mutable(sv, lp, flags) \
+#define SvPV_force_flags_mutable(sv, len, flags) \
     (SvPOK_pure_nogthink(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX_mutable(sv)) \
-     : sv_pvn_force_flags(sv, &lp, flags|SV_MUTABLE_RETURN))
+     ? ((len = SvCUR(sv)), SvPVX_mutable(sv)) \
+     : sv_pvn_force_flags(sv, &len, flags|SV_MUTABLE_RETURN))
 
 #define SvPV_nolen(sv) \
     (SvPOK_nog(sv) \
@@ -1715,19 +1883,33 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
     (SvPOK_nog(sv) \
      ? SvPVX_const(sv) : sv_2pv_flags(sv, 0, SV_GMAGIC|SV_CONST_RETURN))
 
-#define SvPV_nomg(sv, lp) SvPV_flags(sv, lp, 0)
-#define SvPV_nomg_const(sv, lp) SvPV_flags_const(sv, lp, 0)
+#define SvPV_nomg(sv, len) SvPV_flags(sv, len, 0)
+#define SvPV_nomg_const(sv, len) SvPV_flags_const(sv, len, 0)
 #define SvPV_nomg_const_nolen(sv) SvPV_flags_const_nolen(sv, 0)
 
 /* ----*/
 
-#define SvPVutf8(sv, lp) \
+#define SvPVutf8(sv, len) \
     (SvPOK_utf8_nog(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8(sv, &lp))
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8(sv, &len))
 
-#define SvPVutf8_force(sv, lp) \
+#define SvPVutf8_or_null(sv, len) \
+    (SvPOK_utf8_nog(sv) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : (SvGETMAGIC(sv), SvOK(sv)) \
+     ? sv_2pvutf8_flags(sv, &len, 0) : ((len = 0), NULL))
+
+#define SvPVutf8_nomg(sv, len) \
+    (SvPOK_utf8_nog(sv) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvutf8_flags(sv, &len, 0))
+
+#define SvPVutf8_or_null_nomg(sv, len) \
+    (SvPOK_utf8_nog(sv) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : SvOK(sv) \
+     ? sv_2pvutf8_flags(sv, &len, 0) : ((len = 0), NULL))
+
+#define SvPVutf8_force(sv, len) \
     (SvPOK_utf8_pure_nogthink(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvutf8n_force(sv, &lp))
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_pvutf8n_force(sv, &len))
 
 #define SvPVutf8_nolen(sv) \
     (SvPOK_utf8_nog(sv) \
@@ -1735,13 +1917,27 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 
 /* ----*/
 
-#define SvPVbyte(sv, lp) \
+#define SvPVbyte(sv, len) \
+    (SvPOK_byte_nog(sv) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvbyte(sv, &len))
+
+#define SvPVbyte_or_null(sv, len) \
     (SvPOK_byte_nog(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_2pvbyte(sv, &lp))
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : (SvGETMAGIC(sv), SvOK(sv)) \
+     ? sv_2pvbyte_flags(sv, &len, 0) : ((len = 0), NULL))
 
-#define SvPVbyte_force(sv, lp) \
+#define SvPVbyte_nomg(sv, len) \
+    (SvPOK_byte_nog(sv) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_2pvbyte_flags(sv, &len, 0))
+
+#define SvPVbyte_or_null_nomg(sv, len) \
+    (SvPOK_utf8_nog(sv) \
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : SvOK(sv) \
+     ? sv_2pvbyte_flags(sv, &len, 0) : ((len = 0), NULL))
+
+#define SvPVbyte_force(sv, len) \
     (SvPOK_byte_pure_nogthink(sv) \
-     ? ((lp = SvCUR(sv)), SvPVX(sv)) : sv_pvbyten_force(sv, &lp))
+     ? ((len = SvCUR(sv)), SvPVX(sv)) : sv_pvbyten_force(sv, &len))
 
 #define SvPVbyte_nolen(sv) \
     (SvPOK_byte_nog(sv) \
@@ -1753,38 +1949,26 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
  * failing that, call a function to do the work
  */
 
-#define SvPVx_force(sv, lp) sv_pvn_force(sv, &lp)
-#define SvPVutf8x_force(sv, lp) sv_pvutf8n_force(sv, &lp)
-#define SvPVbytex_force(sv, lp) sv_pvbyten_force(sv, &lp)
-
-#define SvTRUE(sv)        (LIKELY(sv) && (UNLIKELY(SvGMAGICAL(sv)) ? sv_2bool(sv) : SvTRUE_common(sv, sv_2bool_nomg(sv))))
-#define SvTRUE_nomg(sv)   (LIKELY(sv) && (                                SvTRUE_common(sv, sv_2bool_nomg(sv))))
-#define SvTRUE_NN(sv)              (UNLIKELY(SvGMAGICAL(sv)) ? sv_2bool(sv) : SvTRUE_common(sv, sv_2bool_nomg(sv)))
-#define SvTRUE_nomg_NN(sv) (                                        SvTRUE_common(sv, sv_2bool_nomg(sv)))
-#define SvTRUE_common(sv,fallback) (                   \
-      !SvOK(sv)                                                \
-       ? 0                                             \
-    : SvPOK(sv)                                                \
-       ? SvPVXtrue(sv)                                 \
-    : (SvFLAGS(sv) & (SVf_IOK|SVf_NOK))                        \
-       ? (   (SvIOK(sv) && SvIVX(sv) != 0)             \
-          || (SvNOK(sv) && SvNVX(sv) != 0.0))          \
-    : (fallback))
-
-#if defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
+#define SvPVx_force(sv, len) sv_pvn_force(sv, &len)
+#define SvPVutf8x_force(sv, len) sv_pvutf8n_force(sv, &len)
+#define SvPVbytex_force(sv, len) sv_pvbyten_force(sv, &len)
+
+#define SvTRUEx(sv)        SvTRUE(sv)
+#define SvTRUEx_nomg(sv)   SvTRUE_nomg(sv)
+#define SvTRUE_nomg_NN(sv) SvTRUE_common(sv, TRUE)
+
+#if defined(PERL_USE_GCC_BRACE_GROUPS)
 
 #  define SvIVx(sv) ({SV *_sv = MUTABLE_SV(sv); SvIV(_sv); })
 #  define SvUVx(sv) ({SV *_sv = MUTABLE_SV(sv); SvUV(_sv); })
 #  define SvNVx(sv) ({SV *_sv = MUTABLE_SV(sv); SvNV(_sv); })
-#  define SvPVx(sv, lp) ({SV *_sv = (sv); SvPV(_sv, lp); })
-#  define SvPVx_const(sv, lp) ({SV *_sv = (sv); SvPV_const(_sv, lp); })
+#  define SvPVx(sv, len) ({SV *_sv = (sv); SvPV(_sv, len); })
+#  define SvPVx_const(sv, len) ({SV *_sv = (sv); SvPV_const(_sv, len); })
 #  define SvPVx_nolen(sv) ({SV *_sv = (sv); SvPV_nolen(_sv); })
 #  define SvPVx_nolen_const(sv) ({SV *_sv = (sv); SvPV_nolen_const(_sv); })
-#  define SvPVutf8x(sv, lp) ({SV *_sv = (sv); SvPVutf8(_sv, lp); })
-#  define SvPVbytex(sv, lp) ({SV *_sv = (sv); SvPVbyte(_sv, lp); })
+#  define SvPVutf8x(sv, len) ({SV *_sv = (sv); SvPVutf8(_sv, len); })
+#  define SvPVbytex(sv, len) ({SV *_sv = (sv); SvPVbyte(_sv, len); })
 #  define SvPVbytex_nolen(sv) ({SV *_sv = (sv); SvPVbyte_nolen(_sv); })
-#  define SvTRUEx(sv)      ({SV *_sv = (sv); SvTRUE(_sv); })
-#  define SvTRUEx_nomg(sv) ({SV *_sv = (sv); SvTRUE_nomg(_sv); })
 
 #else /* __GNUC__ */
 
@@ -1794,15 +1978,13 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 #  define SvIVx(sv) ((PL_Sv = (sv)), SvIV(PL_Sv))
 #  define SvUVx(sv) ((PL_Sv = (sv)), SvUV(PL_Sv))
 #  define SvNVx(sv) ((PL_Sv = (sv)), SvNV(PL_Sv))
-#  define SvPVx(sv, lp) ((PL_Sv = (sv)), SvPV(PL_Sv, lp))
-#  define SvPVx_const(sv, lp) ((PL_Sv = (sv)), SvPV_const(PL_Sv, lp))
+#  define SvPVx(sv, len) ((PL_Sv = (sv)), SvPV(PL_Sv, len))
+#  define SvPVx_const(sv, len) ((PL_Sv = (sv)), SvPV_const(PL_Sv, len))
 #  define SvPVx_nolen(sv) ((PL_Sv = (sv)), SvPV_nolen(PL_Sv))
 #  define SvPVx_nolen_const(sv) ((PL_Sv = (sv)), SvPV_nolen_const(PL_Sv))
-#  define SvPVutf8x(sv, lp) ((PL_Sv = (sv)), SvPVutf8(PL_Sv, lp))
-#  define SvPVbytex(sv, lp) ((PL_Sv = (sv)), SvPVbyte(PL_Sv, lp))
+#  define SvPVutf8x(sv, len) ((PL_Sv = (sv)), SvPVutf8(PL_Sv, len))
+#  define SvPVbytex(sv, len) ((PL_Sv = (sv)), SvPVbyte(PL_Sv, len))
 #  define SvPVbytex_nolen(sv) ((PL_Sv = (sv)), SvPVbyte_nolen(PL_Sv))
-#  define SvTRUEx(sv)      ((PL_Sv = (sv)), SvTRUE(PL_Sv))
-#  define SvTRUEx_nomg(sv) ((PL_Sv = (sv)), SvTRUE_nomg(PL_Sv))
 #endif /* __GNU__ */
 
 #define SvPVXtrue(sv)  (                                       \
@@ -1823,13 +2005,26 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 
 #define SvSHARED_HEK_FROM_PV(pvx) \
        ((struct hek*)(pvx - STRUCT_OFFSET(struct hek, hek_key)))
+/*
+=for apidoc Am|struct hek*|SvSHARED_HASH|SV * sv
+Returns the hash for C<sv> created by C<L</newSVpvn_share>>.
+
+=cut
+*/
 #define SvSHARED_HASH(sv) (0 + SvSHARED_HEK_FROM_PV(SvPVX_const(sv))->hek_hash)
 
 /* flag values for sv_*_flags functions */
+#define SV_UTF8_NO_ENCODING    0       /* No longer used */
+
+/*
+=for apidoc AmnhD||SV_UTF8_NO_ENCODING
+
+=cut
+*/
+
 #define SV_IMMEDIATE_UNREF     1
 #define SV_GMAGIC              2
 #define SV_COW_DROP_PV         4
-#define SV_UTF8_NO_ENCODING    8
 #define SV_NOSTEAL             16
 #define SV_CONST_RETURN                32
 #define SV_MUTABLE_RETURN      64
@@ -1889,7 +2084,7 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
                            && SvCUR(sv)+1 < SvLEN(sv))
    /* Note: To allow 256 COW "copies", a refcnt of 0 means 1. */
 #   define CowREFCNT(sv)       (*(U8 *)(SvPVX(sv)+SvLEN(sv)-1))
-#   define SV_COW_REFCNT_MAX   ((1 << sizeof(U8)*8) - 1)
+#   define SV_COW_REFCNT_MAX   nBIT_UMAX(sizeof(U8) * CHARBITS)
 #   define CAN_COW_MASK        (SVf_POK|SVf_ROK|SVp_POK|SVf_FAKE| \
                         SVf_OOK|SVf_BREAK|SVf_READONLY|SVf_PROTECT)
 #endif
@@ -1909,6 +2104,8 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 #define sv_pvn_force_nomg(sv, lp) sv_pvn_force_flags(sv, lp, 0)
 #define sv_utf8_upgrade_flags(sv, flags) sv_utf8_upgrade_flags_grow(sv, flags, 0)
 #define sv_utf8_upgrade_nomg(sv) sv_utf8_upgrade_flags(sv, 0)
+#define sv_utf8_downgrade(sv, fail_ok) sv_utf8_downgrade_flags(sv, fail_ok, SV_GMAGIC)
+#define sv_utf8_downgrade_nomg(sv, fail_ok) sv_utf8_downgrade_flags(sv, fail_ok, 0)
 #define sv_catpvn_nomg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, 0)
 #define sv_catpv_nomg(dsv, sstr) sv_catpv_flags(dsv, sstr, 0)
 #define sv_setsv(dsv, ssv) \
@@ -1918,12 +2115,14 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 #define sv_catsv_nomg(dsv, ssv) sv_catsv_flags(dsv, ssv, 0)
 #define sv_catsv_mg(dsv, ssv) sv_catsv_flags(dsv, ssv, SV_GMAGIC|SV_SMAGIC)
 #define sv_catpvn(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC)
-#define sv_catpvn_mg(sv, sstr, slen) sv_catpvn_flags(sv, sstr, slen, SV_GMAGIC|SV_SMAGIC);
+#define sv_catpvn_mg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC|SV_SMAGIC);
 #define sv_copypv(dsv, ssv) sv_copypv_flags(dsv, ssv, SV_GMAGIC)
 #define sv_copypv_nomg(dsv, ssv) sv_copypv_flags(dsv, ssv, 0)
 #define sv_2pv(sv, lp) sv_2pv_flags(sv, lp, SV_GMAGIC)
 #define sv_2pv_nolen(sv) sv_2pv(sv, 0)
+#define sv_2pvbyte(sv, lp) sv_2pvbyte_flags(sv, lp, SV_GMAGIC)
 #define sv_2pvbyte_nolen(sv) sv_2pvbyte(sv, 0)
+#define sv_2pvutf8(sv, lp) sv_2pvutf8_flags(sv, lp, SV_GMAGIC)
 #define sv_2pvutf8_nolen(sv) sv_2pvutf8(sv, 0)
 #define sv_2pv_nomg(sv, lp) sv_2pv_flags(sv, lp, 0)
 #define sv_pvn_force(sv, lp) sv_pvn_force_flags(sv, lp, SV_GMAGIC)
@@ -1934,7 +2133,7 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 #define sv_eq(sv1, sv2) sv_eq_flags(sv1, sv2, SV_GMAGIC)
 #define sv_cmp(sv1, sv2) sv_cmp_flags(sv1, sv2, SV_GMAGIC)
 #define sv_cmp_locale(sv1, sv2) sv_cmp_locale_flags(sv1, sv2, SV_GMAGIC)
-#define sv_collxfrm(sv, nxp) sv_cmp_flags(sv, nxp, SV_GMAGIC)
+#define sv_collxfrm(sv, nxp) sv_collxfrm_flags(sv, nxp, SV_GMAGIC)
 #define sv_2bool(sv) sv_2bool_flags(sv, SV_GMAGIC)
 #define sv_2bool_nomg(sv) sv_2bool_flags(sv, 0)
 #define sv_insert(bigstr, offset, len, little, littlelen)              \
@@ -1971,10 +2170,11 @@ Like C<sv_utf8_upgrade>, but doesn't do magic on C<sv>.
 #endif
 
 /*
-=for apidoc Am|SV*|newRV_inc|SV* sv
+=for apidoc newRV
+=for apidoc_item ||newRV_inc|
 
-Creates an RV wrapper for an SV.  The reference count for the original SV is
-incremented.
+These are identical.  They create an RV wrapper for an SV.  The reference count
+for the original SV is incremented.
 
 =cut
 */
@@ -1984,32 +2184,35 @@ incremented.
 /* the following macros update any magic values this C<sv> is associated with */
 
 /*
-=head1 Magical Functions
+=for apidoc_section $SV
 
 =for apidoc Am|void|SvGETMAGIC|SV* sv
-Invokes C<mg_get> on an SV if it has 'get' magic.  For example, this
+Invokes C<L</mg_get>> on an SV if it has 'get' magic.  For example, this
 will call C<FETCH> on a tied variable.  This macro evaluates its
 argument more than once.
 
 =for apidoc Am|void|SvSETMAGIC|SV* sv
-Invokes C<mg_set> on an SV if it has 'set' magic.  This is necessary
+Invokes C<L</mg_set>> on an SV if it has 'set' magic.  This is necessary
 after modifying a scalar, in case it is a magical variable like C<$|>
 or a tied variable (it calls C<STORE>).  This macro evaluates its
 argument more than once.
 
 =for apidoc Am|void|SvSetSV|SV* dsv|SV* ssv
-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_item SvSetMagicSV
+=for apidoc_item SvSetSV_nosteal
+=for apidoc_item SvSetMagicSV_nosteal
 
-=for apidoc Am|void|SvSetSV_nosteal|SV* dsv|SV* ssv
-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.
+if C<dsv> is the same as C<ssv>, these do nothing.  Otherwise they all call
+some form of C<L</sv_setsv>>.  They may evaluate their arguments more than
+once.
 
-=for apidoc Am|void|SvSetMagicSV|SV* dsv|SV* ssv
-Like C<SvSetSV>, but does any set magic required afterwards.
+The only differences are:
 
-=for apidoc Am|void|SvSetMagicSV_nosteal|SV* dsv|SV* ssv
-Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
+C<SvSetMagicSV> and C<SvSetMagicSV_nosteal> perform any required 'set' magic
+afterwards on the destination SV; C<SvSetSV> and C<SvSetSV_nosteal> do not.
+
+C<SvSetSV_nosteal> C<SvSetMagicSV_nosteal> call a non-destructive version of
+C<sv_setsv>.
 
 =for apidoc Am|void|SvSHARE|SV* sv
 Arranges for C<sv> to be shared between threads if a suitable module
@@ -2023,7 +2226,7 @@ has been loaded.
 Releases a mutual exclusion lock on C<sv> if a suitable module
 has been loaded.
 
-=head1 SV Manipulation Functions
+=for apidoc_section $SV
 
 =for apidoc Am|char *|SvGROW|SV* sv|STRLEN len
 Expands the character buffer in the SV so that it has room for the
@@ -2033,6 +2236,9 @@ Returns a pointer to the character
 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.
 
+You might mistakenly think that C<len> is the number of bytes to add to the
+existing size, but instead it is the total size C<sv> should be.
+
 =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.
@@ -2081,7 +2287,20 @@ properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
 #define SvPEEK(sv) ""
 #endif
 
-#define SvIMMORTAL(sv) (SvREADONLY(sv) && ((sv)==&PL_sv_undef || (sv)==&PL_sv_yes || (sv)==&PL_sv_no || (sv)==&PL_sv_placeholder))
+/* Is this a per-interpreter immortal SV (rather than global)?
+ * These should either occupy adjacent entries in the interpreter struct
+ * (MULTIPLICITY) or adjacent elements of PL_sv_immortals[] otherwise.
+ * The unsigned (Size_t) cast avoids the need for a second < 0 condition.
+ */
+#define SvIMMORTAL_INTERP(sv) ((Size_t)((sv) - &PL_sv_yes) < 4)
+
+/* Does this immortal have a true value? Currently only PL_sv_yes does. */
+#define SvIMMORTAL_TRUE(sv)   ((sv) == &PL_sv_yes)
+
+/* the SvREADONLY() test is to quickly reject most SVs */
+#define SvIMMORTAL(sv) \
+                (  SvREADONLY(sv) \
+                && (SvIMMORTAL_INTERP(sv) || (sv) == &PL_sv_placeholder))
 
 #ifdef DEBUGGING
    /* exercise the immortal resurrection code in sv_free2() */
@@ -2105,6 +2324,13 @@ See also C<L</PL_sv_yes>> and C<L</PL_sv_no>>.
 #define isGV(sv) (SvTYPE(sv) == SVt_PVGV)
 /* If I give every macro argument a different name, then there won't be bugs
    where nested macros get confused. Been there, done that.  */
+/*
+=for apidoc Am|bool|isGV_with_GP|SV * sv
+Returns a boolean as to whether or not C<sv> is a GV with a pointer to a GP
+(glob pointer).
+
+=cut
+*/
 #define isGV_with_GP(pwadak) \
        (((SvFLAGS(pwadak) & (SVp_POK|SVpgv_GP)) == SVpgv_GP)   \
        && (SvTYPE(pwadak) == SVt_PVGV || SvTYPE(pwadak) == SVt_PVLV))
@@ -2120,9 +2346,13 @@ See also C<L</PL_sv_yes>> and C<L</PL_sv_no>>.
        assert (!SvIOKp(sv));                                          \
        (SvFLAGS(sv) &= ~SVpgv_GP);                                    \
     } STMT_END
+#ifdef PERL_CORE
+# define isGV_or_RVCV(kadawp) \
+    (isGV(kadawp) || (SvROK(kadawp) && SvTYPE(SvRV(kadawp)) == SVt_PVCV))
+#endif
 #define isREGEXP(sv) \
     (SvTYPE(sv) == SVt_REGEXP                                \
-     || (SvFLAGS(sv) & (SVTYPEMASK|SVp_POK|SVpgv_GP|SVf_FAKE)) \
+     || (SvFLAGS(sv) & (SVTYPEMASK|SVpgv_GP|SVf_FAKE))        \
         == (SVt_PVLV|SVf_FAKE))
 
 
@@ -2149,8 +2379,13 @@ struct clone_params {
   AV *unreferenced;
 };
 
+/* SV_NOSTEAL prevents TEMP buffers being, well, stolen, and saves games
+   with SvTEMP_off and SvTEMP_on round a call to sv_setsv.  */
+#define newSVsv(sv) newSVsv_flags((sv), SV_GMAGIC|SV_NOSTEAL)
+#define newSVsv_nomg(sv) newSVsv_flags((sv), SV_NOSTEAL)
+
 /*
-=for apidoc Am|SV*|newSVpvn_utf8|NULLOK const char* s|STRLEN len|U32 utf8
+=for apidoc Am|SV*|newSVpvn_utf8|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 C<utf8> is true, calls
@@ -2172,7 +2407,7 @@ Creates a new SV containing the pad name.
 #define newSVpadname(pn) newSVpvn_utf8(PadnamePV(pn), PadnameLEN(pn), TRUE)
 
 /*
-=for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len
+=for apidoc Am|void|SvOOK_offset|SV*sv|STRLEN len
 
 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
@@ -2189,7 +2424,7 @@ Evaluates C<sv> more than once.  Sets C<len> to 0 if C<SvOOK(sv)> is false.
 10:28 <+meta> Nicholas: crash
 */
 #  define SvOOK_offset(sv, offset) STMT_START {                                \
-       assert(sizeof(offset) == sizeof(STRLEN));                       \
+       STATIC_ASSERT_STMT(sizeof(offset) == sizeof(STRLEN));           \
        if (SvOOK(sv)) {                                                \
            const U8 *_crash = (U8*)SvPVX_const(sv);                    \
            (offset) = *--_crash;                                       \
@@ -2213,7 +2448,7 @@ Evaluates C<sv> more than once.  Sets C<len> to 0 if C<SvOOK(sv)> is false.
 #else
     /* This is the same code, but avoids using any temporary variables:  */
 #  define SvOOK_offset(sv, offset) STMT_START {                                \
-       assert(sizeof(offset) == sizeof(STRLEN));                       \
+       STATIC_ASSERT_STMT(sizeof(offset) == sizeof(STRLEN));           \
        if (SvOOK(sv)) {                                                \
            (offset) = ((U8*)SvPVX_const(sv))[-1];                      \
            if (!(offset)) {                                            \
@@ -2228,51 +2463,54 @@ Evaluates C<sv> more than once.  Sets C<len> to 0 if C<SvOOK(sv)> is false.
 
 #define newIO()        MUTABLE_IO(newSV_type(SVt_PVIO))
 
-#define SV_CONST(name) \
+#if defined(PERL_CORE) || defined(PERL_EXT)
+
+#  define SV_CONST(name) \
        PL_sv_consts[SV_CONST_##name] \
                ? PL_sv_consts[SV_CONST_##name] \
                : (PL_sv_consts[SV_CONST_##name] = newSVpv_share(#name, 0))
 
-#define SV_CONST_TIESCALAR 0
-#define SV_CONST_TIEARRAY 1
-#define SV_CONST_TIEHASH 2
-#define SV_CONST_TIEHANDLE 3
-
-#define SV_CONST_FETCH 4
-#define SV_CONST_FETCHSIZE 5
-#define SV_CONST_STORE 6
-#define SV_CONST_STORESIZE 7
-#define SV_CONST_EXISTS 8
-
-#define SV_CONST_PUSH 9
-#define SV_CONST_POP 10
-#define SV_CONST_SHIFT 11
-#define SV_CONST_UNSHIFT 12
-#define SV_CONST_SPLICE 13
-#define SV_CONST_EXTEND 14
-
-#define SV_CONST_FIRSTKEY 15
-#define SV_CONST_NEXTKEY 16
-#define SV_CONST_SCALAR 17
-
-#define SV_CONST_OPEN 18
-#define SV_CONST_WRITE 19
-#define SV_CONST_PRINT 20
-#define SV_CONST_PRINTF 21
-#define SV_CONST_READ 22
-#define SV_CONST_READLINE 23
-#define SV_CONST_GETC 24
-#define SV_CONST_SEEK 25
-#define SV_CONST_TELL 26
-#define SV_CONST_EOF 27
-#define SV_CONST_BINMODE 28
-#define SV_CONST_FILENO 29
-#define SV_CONST_CLOSE 30
-
-#define SV_CONST_DELETE 31
-#define SV_CONST_CLEAR 32
-#define SV_CONST_UNTIE 33
-#define SV_CONST_DESTROY 34
+#  define SV_CONST_TIESCALAR 0
+#  define SV_CONST_TIEARRAY 1
+#  define SV_CONST_TIEHASH 2
+#  define SV_CONST_TIEHANDLE 3
+
+#  define SV_CONST_FETCH 4
+#  define SV_CONST_FETCHSIZE 5
+#  define SV_CONST_STORE 6
+#  define SV_CONST_STORESIZE 7
+#  define SV_CONST_EXISTS 8
+
+#  define SV_CONST_PUSH 9
+#  define SV_CONST_POP 10
+#  define SV_CONST_SHIFT 11
+#  define SV_CONST_UNSHIFT 12
+#  define SV_CONST_SPLICE 13
+#  define SV_CONST_EXTEND 14
+
+#  define SV_CONST_FIRSTKEY 15
+#  define SV_CONST_NEXTKEY 16
+#  define SV_CONST_SCALAR 17
+
+#  define SV_CONST_OPEN 18
+#  define SV_CONST_WRITE 19
+#  define SV_CONST_PRINT 20
+#  define SV_CONST_PRINTF 21
+#  define SV_CONST_READ 22
+#  define SV_CONST_READLINE 23
+#  define SV_CONST_GETC 24
+#  define SV_CONST_SEEK 25
+#  define SV_CONST_TELL 26
+#  define SV_CONST_EOF 27
+#  define SV_CONST_BINMODE 28
+#  define SV_CONST_FILENO 29
+#  define SV_CONST_CLOSE 30
+
+#  define SV_CONST_DELETE 31
+#  define SV_CONST_CLEAR 32
+#  define SV_CONST_UNTIE 33
+#  define SV_CONST_DESTROY 34
+#endif
 
 #define SV_CONSTS_COUNT 35