This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Add 2 links to other parts of the pod
[perl5.git] / sv.h
diff --git a/sv.h b/sv.h
index 6c77cce..665c330 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -349,7 +349,7 @@ perform the upgrade if necessary.  See C<svtype>.
 /* Sadly there are some parts of the core that have pointers to already-freed
    SV heads, and rely on being able to tell that they are now free. So mark
    them all by using a consistent macro.  */
-#define SvIS_FREED(sv) ((sv)->sv_flags == SVTYPEMASK)
+#define SvIS_FREED(sv) UNLIKELY(((sv)->sv_flags == SVTYPEMASK))
 
 /* this is defined in this peculiar way to avoid compiler warnings.
  * See the <20121213131428.GD1842@iabyn.com> thread in p5p */
@@ -371,16 +371,12 @@ perform the upgrade if necessary.  See C<svtype>.
                                       subroutine in another package. Set the
                                       GvIMPORTED_CV_on() if it needs to be
                                       expanded to a real GV */
-#define SVpad_NAMELIST SVp_SCREAM  /* AV is a padnamelist */
 #define SVf_PROTECT    0x00010000  /* very read-only */
 #define SVs_PADTMP     0x00020000  /* in use as tmp */
-#define SVpad_TYPED    0x00020000  /* pad name is a Typed Lexical */
 #define SVs_PADSTALE   0x00040000  /* lexical has gone out of scope;
                                        only used when !PADTMP */
-#define SVpad_OUR      0x00040000  /* pad name is "our" instead of "my" */
 #define SVs_TEMP       0x00080000  /* mortal (implies string is stealable) */
 #define SVs_OBJECT     0x00100000  /* is "blessed" */
-#define SVpad_LVALUE   0x00100000  /* pad name is used as lvalue */
 #define SVs_GMG                0x00200000  /* has magical get method */
 #define SVs_SMG                0x00400000  /* has magical set method */
 #define SVs_RMG                0x00800000  /* has random magical methods */
@@ -390,10 +386,7 @@ perform the upgrade if necessary.  See C<svtype>.
                                       2: For PVCV, whether CvUNIQUE(cv)
                                          refers to an eval or once only
                                          [CvEVAL(cv), CvSPECIAL(cv)]
-                                      3: On a pad name SV, that slot in the
-                                         frame AV is a REFCNT'ed reference
-                                         to a lexical from "outside".
-                                       4: HV: informally reserved by DAPM
+                                       3: HV: informally reserved by DAPM
                                           for vtables */
 #define SVf_OOK                0x02000000  /* has valid offset value. For a PVHV this
                                       means that a hv_aux struct is present
@@ -437,22 +430,19 @@ perform the upgrade if necessary.  See C<svtype>.
 /* Some private flags. */
 
 
-/* PVNV, PVMG only, and only used in pads. Should be safe to test on any scalar
-   SV, as the core is careful to avoid setting both.
+/* 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   pad name.
+   0x4000C400   *** Formerly used for pad names ***
 
    0x00008000   GV with GP
    0x00008800   RV with PCS imported
 */
-#define SVpad_NAME     (SVp_SCREAM|SVpbm_VALID)
-                                   /* This SV is a name in the PAD, so
-                                      SVpad_TYPED, SVpad_OUR and SVpad_STATE
-                                      apply */
 /* PVAV */
 #define SVpav_REAL     0x40000000  /* free old entries */
 /* PVHV */
@@ -474,7 +464,6 @@ perform the upgrade if necessary.  See C<svtype>.
 /* RV upwards. However, SVf_ROK and SVp_IOK are exclusive  */
 #define SVprv_WEAKREF   0x80000000  /* Weak reference */
 /* pad name vars only */
-#define SVpad_STATE    0x80000000  /* pad name is a "state" var */
 
 #define _XPV_HEAD                                                      \
     HV*                xmg_stash;      /* class package */                     \
@@ -504,9 +493,8 @@ union _xivu {
 
 union _xmgu {
     MAGIC*  xmg_magic;         /* linked list of magicalness */
-    HV*            xmg_ourstash;       /* Stash for our (when SvPAD_OUR is true) */
     STRLEN  xmg_hash_index;    /* used while freeing hash entries */
-};                             /* also used by PadnamelistMAXNAMED */
+};
 
 struct xpv {
     _XPV_HEAD;
@@ -813,13 +801,18 @@ C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
 Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
 
 =for apidoc Am|void|SvPV_set|SV* sv|char* val
-Set the value of the PV pointer in C<sv> to the C<NUL>-terminated string
-C<val>.  See also C<SvIV_set>.
+This is probably not what you want to use, you probably wanted
+L</sv_usepvn_flags> or L</sv_setpvn> or L</sv_setpvs>.
+
+Set the value of the PV pointer in C<sv> to the Perl allocated
+C<NUL>-terminated string C<val>.  See also C<SvIV_set>.
 
+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
-modification is safe.
+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<SvIV_set>.
@@ -904,6 +897,9 @@ 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
 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>>
+instead.
+
 =for apidoc Am|void|SvUTF8_on|SV *sv
 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
 Do not use frivolously.
@@ -1144,47 +1140,6 @@ sv_force_normal does nothing.
 #define SvTAIL_on(sv)          (SvFLAGS(sv) |= SVpbm_TAIL)
 #define SvTAIL_off(sv)         (SvFLAGS(sv) &= ~SVpbm_TAIL)
 
-#define SvPAD_NAME(sv) ((SvFLAGS(sv) & SVpad_NAME) == SVpad_NAME)
-
-#define SvPAD_TYPED(sv) \
-       ((SvFLAGS(sv) & (SVpad_NAME|SVpad_TYPED)) == (SVpad_NAME|SVpad_TYPED))
-
-#define SvPAD_OUR(sv)  \
-       ((SvFLAGS(sv) & (SVpad_NAME|SVpad_OUR)) == (SVpad_NAME|SVpad_OUR))
-
-#define SvPAD_STATE(sv)        \
-       ((SvFLAGS(sv) & (SVpad_NAME|SVpad_STATE)) == (SVpad_NAME|SVpad_STATE))
-
-#if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
-#  define SvPAD_TYPED_on(sv)   ({                                      \
-           SV *const _svpad = MUTABLE_SV(sv);                          \
-           assert(SvTYPE(_svpad) == SVt_PVMG);                         \
-           (SvFLAGS(_svpad) |= SVpad_NAME|SVpad_TYPED);                \
-       })
-#define SvPAD_OUR_on(sv)       ({                                      \
-           SV *const _svpad = MUTABLE_SV(sv);                          \
-           assert(SvTYPE(_svpad) == SVt_PVMG);                         \
-           (SvFLAGS(_svpad) |= SVpad_NAME|SVpad_OUR);                  \
-       })
-#define SvPAD_STATE_on(sv)     ({                                      \
-           SV *const _svpad = MUTABLE_SV(sv);                          \
-           assert(SvTYPE(_svpad) == SVt_PVNV || SvTYPE(_svpad) == SVt_PVMG); \
-           (SvFLAGS(_svpad) |= SVpad_NAME|SVpad_STATE);                \
-       })
-#else
-#  define SvPAD_TYPED_on(sv)   (SvFLAGS(sv) |= SVpad_NAME|SVpad_TYPED)
-#  define SvPAD_OUR_on(sv)     (SvFLAGS(sv) |= SVpad_NAME|SVpad_OUR)
-#  define SvPAD_STATE_on(sv)   (SvFLAGS(sv) |= SVpad_NAME|SVpad_STATE)
-#endif
-
-#define SvOURSTASH(sv) \
-       (SvPAD_OUR(sv) ? ((XPVMG*) SvANY(sv))->xmg_u.xmg_ourstash : NULL)
-#define SvOURSTASH_set(sv, st)                                 \
-        STMT_START {                                           \
-           assert(SvTYPE(sv) == SVt_PVMG);                     \
-           ((XPVMG*) SvANY(sv))->xmg_u.xmg_ourstash = st;      \
-       } STMT_END
-
 #define SvRVx(sv) SvRV(sv)
 
 #ifdef PERL_DEBUG_COW
@@ -1267,8 +1222,6 @@ sv_force_normal does nothing.
 #    define SvMAGIC(sv)                                                        \
        (*({ const SV *const _svmagic = (const SV *)(sv);               \
            assert(SvTYPE(_svmagic) >= SVt_PVMG);                       \
-           if(SvTYPE(_svmagic) == SVt_PVMG)                            \
-               assert(!SvPAD_OUR(_svmagic));                           \
            &(((XPVMG*) MUTABLE_PTR(SvANY(_svmagic)))->xmg_u.xmg_magic); \
          }))
 #    define SvSTASH(sv)                                                        \
@@ -1313,11 +1266,11 @@ sv_force_normal does nothing.
    Not guaranteed to stay returning void */
 /* Macro won't actually call sv_2iv if already IOK */
 #define SvIV_please(sv) \
-       STMT_START {if (!SvIOKp(sv) && (SvNOK(sv) || SvPOK(sv))) \
+       STMT_START {if (!SvIOKp(sv) && (SvFLAGS(sv) & (SVf_NOK|SVf_POK))) \
                (void) SvIV(sv); } STMT_END
 #define SvIV_please_nomg(sv) \
-       (!SvIOKp(sv) && (SvNOK(sv) || SvPOK(sv)) \
-           ? (SvIV_nomg(sv), SvIOK(sv))          \
+       (!(SvFLAGS(sv) & (SVf_IOK|SVp_IOK)) && (SvFLAGS(sv) & (SVf_NOK|SVf_POK)) \
+           ? (sv_2iv_flags(sv, 0), SvIOK(sv))    \
            : SvIOK(sv))
 #define SvIV_set(sv, val) \
        STMT_START { \
@@ -2205,14 +2158,12 @@ C<SvUTF8_on> on the new SV.  Implemented as a wrapper around C<newSVpvn_flags>.
 /*
 =for apidoc Amx|SV*|newSVpadname|PADNAME *pn
 
-Creates a new SV containing the pad name.  This is currently identical
-to C<newSVsv>, but pad names may cease being SVs at some point, so
-C<newSVpadname> is preferable.
+Creates a new SV containing the pad name.
 
 =cut
 */
 
-#define newSVpadname(pn) newSVsv(pn)
+#define newSVpadname(pn) newSVpvn_utf8(PadnamePV(pn), PadnameLEN(pn), TRUE)
 
 /*
 =for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len
@@ -2320,11 +2271,5 @@ Evaluates I<sv> more than once.  Sets I<len> to 0 if C<SvOOK(sv)> is false.
 #define SV_CONSTS_COUNT 35
 
 /*
- * Local variables:
- * c-indentation-style: bsd
- * c-basic-offset: 4
- * indent-tabs-mode: nil
- * End:
- *
  * ex: set ts=8 sts=4 sw=4 et:
  */