This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
5.12.0 is now expected on 7 April 2010
[perl5.git] / sv.h
diff --git a/sv.h b/sv.h
index 2722083..fc1b475 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -1,7 +1,7 @@
 /*    sv.h
  *
  *    Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
- *    2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 by Larry Wall and others
+ *    2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 by Larry Wall and others
  *
  *    You may distribute under the terms of either the GNU General Public
  *    License or the Artistic License, as specified in the README file.
@@ -103,10 +103,10 @@ typedef struct hek HEK;
 
 #define _SV_HEAD_UNION \
     union {                            \
+       char*   svu_pv;         /* pointer to malloced string */        \
        IV      svu_iv;                 \
        UV      svu_uv;                 \
        SV*     svu_rv;         /* pointer to another SV */             \
-       char*   svu_pv;         /* pointer to malloced string */        \
        SV**    svu_array;              \
        HE**    svu_hash;               \
        GP*     svu_gp;                 \
@@ -398,13 +398,10 @@ perform the upgrade if necessary.  See C<svtype>.
 /* RV upwards. However, SVf_ROK and SVp_IOK are exclusive  */
 #define SVprv_WEAKREF   0x80000000  /* Weak reference */
 
-#define _XPV_ALLOCATED_HEAD                                            \
-    STRLEN     xpv_cur;        /* length of svu_pv as a C string */    \
-    STRLEN     xpv_len         /* allocated size */
-
 #define _XPV_HEAD      \
     union _xnvu xnv_u; \
-    _XPV_ALLOCATED_HEAD
+    STRLEN     xpv_cur;        /* length of svu_pv as a C string */    \
+    STRLEN     xpv_len         /* allocated size */
 
 union _xnvu {
     NV     xnv_nv;             /* numeric value, if any */
@@ -439,20 +436,11 @@ struct xpv {
     _XPV_HEAD;
 };
 
-typedef struct {
-    _XPV_ALLOCATED_HEAD;
-} xpv_allocated;
-
 struct xpviv {
     _XPV_HEAD;
     union _xivu xiv_u;
 };
 
-typedef struct {
-    _XPV_ALLOCATED_HEAD;
-    union _xivu xiv_u;
-} xpviv_allocated;
-
 #define xiv_iv xiv_u.xivu_iv
 
 struct xpvuv {
@@ -472,7 +460,7 @@ struct xpvnv {
     union _xmgu        xmg_u;                              \
     HV*                xmg_stash       /* class package */
 
-/* These structure must match the beginning of struct xpvhv in hv.h. */
+/* This structure must match the beginning of struct xpvhv in hv.h. */
 struct xpvmg {
     _XPV_HEAD;
     _XPVMG_HEAD;
@@ -525,12 +513,6 @@ struct xpvfm {
     _XPVCV_COMMON;
 };
 
-typedef struct {
-    _XPV_ALLOCATED_HEAD;
-    _XPVMG_HEAD;
-    _XPVCV_COMMON;
-} xpvfm_allocated;
-
 #define _XPVIO_TAIL                                                    \
     PerlIO *   xio_ifp;        /* ifp and ofp are normally the same */ \
     PerlIO *   xio_ofp;        /* but sockets need separate streams */ \
@@ -547,7 +529,7 @@ typedef struct {
        DIR *   xiou_dirp;      /* for opendir, readdir, etc */         \
        void *  xiou_any;       /* for alignment */                     \
     } xio_dirpu;                                                       \
-    IV         xio_lines;      /* $. */                                \
+    /* IV xio_lines is now in IVX  $. */                               \
     IV         xio_page;       /* $% */                                \
     IV         xio_page_len;   /* $= */                                \
     IV         xio_lines_left; /* $- */                                \
@@ -567,12 +549,6 @@ struct xpvio {
     _XPVIO_TAIL;
 };
 
-typedef struct {
-    _XPV_ALLOCATED_HEAD;
-    _XPVMG_HEAD;
-    _XPVIO_TAIL;
-} xpvio_allocated;
-
 #define xio_dirp       xio_dirpu.xiou_dirp
 #define xio_any                xio_dirpu.xiou_any
 
@@ -593,26 +569,26 @@ double.
 
 =for apidoc Am|U32|SvNIOKp|SV* sv
 Returns a U32 value indicating whether the SV contains a number, integer or
-double.  Checks the B<private> setting.  Use C<SvNIOK>.
+double.  Checks the B<private> setting.  Use C<SvNIOK> instead.
 
 =for apidoc Am|void|SvNIOK_off|SV* sv
 Unsets the NV/IV status of an SV.
 
 =for apidoc Am|U32|SvOK|SV* sv
-Returns a U32 value indicating whether the value is an SV. It also tells
-whether the value is defined or not.
+Returns a U32 value indicating whether the value is defined. This is
+only meaningful for scalars.
 
 =for apidoc Am|U32|SvIOKp|SV* sv
 Returns a U32 value indicating whether the SV contains an integer.  Checks
-the B<private> setting.  Use C<SvIOK>.
+the B<private> setting.  Use C<SvIOK> instead.
 
 =for apidoc Am|U32|SvNOKp|SV* sv
 Returns a U32 value indicating whether the SV contains a double.  Checks the
-B<private> setting.  Use C<SvNOK>.
+B<private> setting.  Use C<SvNOK> instead.
 
 =for apidoc Am|U32|SvPOKp|SV* sv
 Returns a U32 value indicating whether the SV contains a character string.
-Checks the B<private> setting.  Use C<SvPOK>.
+Checks the B<private> setting.  Use C<SvPOK> instead.
 
 =for apidoc Am|U32|SvIOK|SV* sv
 Returns a U32 value indicating whether the SV contains an integer.
@@ -902,7 +878,7 @@ in gv.h: */
 #endif
 
 /*
-=for apidoc Am|char*|SvGAMAGIC|SV* sv
+=for apidoc Am|U32|SvGAMAGIC|SV* sv
 
 Returns true if the SV has get magic or overloading. If either is true then
 the scalar is active data, and has the potential to return a new value every
@@ -915,7 +891,7 @@ the scalar's value cannot change unless written to.
 
 #define SvGAMAGIC(sv)           (SvGMAGICAL(sv) || SvAMAGIC(sv))
 
-#define Gv_AMG(stash)           (PL_amagic_generation && Gv_AMupdate(stash))
+#define Gv_AMG(stash)           (PL_amagic_generation && Gv_AMupdate(stash, FALSE))
 
 #define SvWEAKREF(sv)          ((SvFLAGS(sv) & (SVf_ROK|SVprv_WEAKREF)) \
                                  == (SVf_ROK|SVprv_WEAKREF))
@@ -1048,6 +1024,7 @@ the scalar's value cannot change unless written to.
 #  define SvUVX(sv) (0 + ((XPVUV*) SvANY(sv))->xuv_uv)
 #  define SvNVX(sv) (-0.0 + ((XPVNV*) SvANY(sv))->xnv_u.xnv_nv)
 #  define SvRV(sv) (0 + (sv)->sv_u.svu_rv)
+#  define SvRV_const(sv) (0 + (sv)->sv_u.svu_rv)
 /* Don't test the core XS code yet.  */
 #  if defined (PERL_CORE) && PERL_DEBUG_COW > 1
 #    define SvPVX(sv) (0 + (assert(!SvREADONLY(sv)), (sv)->sv_u.svu_pv))
@@ -1072,7 +1049,7 @@ the scalar's value cannot change unless written to.
 #  if defined (DEBUGGING) && defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
 /* These get expanded inside other macros that already use a variable _sv  */
 #    define SvPVX(sv)                                                  \
-       (*({ const SV *const _svpvx = (const SV *)(sv);                 \
+       (*({ SV *const _svpvx = MUTABLE_SV(sv);                         \
            assert(SvTYPE(_svpvx) >= SVt_PV);                           \
            assert(SvTYPE(_svpvx) != SVt_PVAV);                         \
            assert(SvTYPE(_svpvx) != SVt_PVHV);                         \
@@ -1094,6 +1071,7 @@ the scalar's value cannot change unless written to.
            assert(SvTYPE(_svivx) != SVt_PVHV);                         \
            assert(SvTYPE(_svivx) != SVt_PVCV);                         \
            assert(SvTYPE(_svivx) != SVt_PVFM);                         \
+           assert(SvTYPE(_svivx) != SVt_PVIO);                         \
            assert(!isGV_with_GP(_svivx));                              \
            &(((XPVIV*) MUTABLE_PTR(SvANY(_svivx)))->xiv_iv);           \
         }))
@@ -1104,6 +1082,7 @@ the scalar's value cannot change unless written to.
            assert(SvTYPE(_svuvx) != SVt_PVHV);                         \
            assert(SvTYPE(_svuvx) != SVt_PVCV);                         \
            assert(SvTYPE(_svuvx) != SVt_PVFM);                         \
+           assert(SvTYPE(_svuvx) != SVt_PVIO);                         \
            assert(!isGV_with_GP(_svuvx));                              \
            &(((XPVUV*) MUTABLE_PTR(SvANY(_svuvx)))->xuv_uv);           \
         }))
@@ -1119,7 +1098,7 @@ the scalar's value cannot change unless written to.
            &(((XPVNV*) MUTABLE_PTR(SvANY(_svnvx)))->xnv_u.xnv_nv);     \
         }))
 #    define SvRV(sv)                                                   \
-       (*({ const SV *const _svrv = (const SV *)(sv);                  \
+       (*({ SV *const _svrv = MUTABLE_SV(sv);                          \
            assert(SvTYPE(_svrv) >= SVt_PV || SvTYPE(_svrv) == SVt_IV); \
            assert(SvTYPE(_svrv) != SVt_PVAV);                          \
            assert(SvTYPE(_svrv) != SVt_PVHV);                          \
@@ -1128,6 +1107,16 @@ the scalar's value cannot change unless written to.
            assert(!isGV_with_GP(_svrv));                               \
            &((_svrv)->sv_u.svu_rv);                                    \
         }))
+#    define SvRV_const(sv)                                             \
+       ({ const SV *const _svrv = (const SV *)(sv);                    \
+           assert(SvTYPE(_svrv) >= SVt_PV || SvTYPE(_svrv) == SVt_IV); \
+           assert(SvTYPE(_svrv) != SVt_PVAV);                          \
+           assert(SvTYPE(_svrv) != SVt_PVHV);                          \
+           assert(SvTYPE(_svrv) != SVt_PVCV);                          \
+           assert(SvTYPE(_svrv) != SVt_PVFM);                          \
+           assert(!isGV_with_GP(_svrv));                               \
+           (_svrv)->sv_u.svu_rv;                                       \
+        })
 #    define SvMAGIC(sv)                                                        \
        (*({ const SV *const _svmagic = (const SV *)(sv);               \
            assert(SvTYPE(_svmagic) >= SVt_PVMG);                       \
@@ -1147,6 +1136,7 @@ the scalar's value cannot change unless written to.
 #    define SvUVX(sv) ((XPVUV*) SvANY(sv))->xuv_uv
 #    define SvNVX(sv) ((XPVNV*) SvANY(sv))->xnv_u.xnv_nv
 #    define SvRV(sv) ((sv)->sv_u.svu_rv)
+#    define SvRV_const(sv) (0 + (sv)->sv_u.svu_rv)
 #    define SvMAGIC(sv)        ((XPVMG*)  SvANY(sv))->xmg_u.xmg_magic
 #    define SvSTASH(sv)        ((XPVMG*)  SvANY(sv))->xmg_stash
 #  endif
@@ -1327,7 +1317,7 @@ the scalar's value cannot change unless written to.
 #define IoOFP(sv)      ((XPVIO*)  SvANY(sv))->xio_ofp
 #define IoDIRP(sv)     ((XPVIO*)  SvANY(sv))->xio_dirp
 #define IoANY(sv)      ((XPVIO*)  SvANY(sv))->xio_any
-#define IoLINES(sv)    ((XPVIO*)  SvANY(sv))->xio_lines
+#define IoLINES(sv)    ((XPVIO*)  SvANY(sv))->xiv_u.xivu_iv
 #define IoPAGE(sv)     ((XPVIO*)  SvANY(sv))->xio_page
 #define IoPAGE_LEN(sv) ((XPVIO*)  SvANY(sv))->xio_page_len
 #define IoLINES_LEFT(sv)((XPVIO*)  SvANY(sv))->xio_lines_left
@@ -1453,7 +1443,7 @@ otherwise use the more efficient C<SvUV>.
 
 =for apidoc Am|bool|SvTRUE|SV* sv
 Returns a boolean indicating whether Perl would evaluate the SV as true or
-false, defined or undefined.  Does not handle 'get' magic.
+false.  See 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.
@@ -1511,6 +1501,10 @@ 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 sv_utf8_upgrade, but doesn't do magic on C<sv>
+
 =cut
 */
 
@@ -1700,6 +1694,10 @@ Like C<sv_catsv> but doesn't process magic.
 #define SV_COW_OTHER_PVS       1024
 /* Make sv_2pv_flags return NULL if something is undefined.  */
 #define SV_UNDEF_RETURNS_NULL  2048
+/* Tell sv_utf8_upgrade() to not check to see if an upgrade is really needed.
+ * This is used when the caller has already determined it is, and avoids
+ * redundant work */
+#define SV_FORCE_UTF8_UPGRADE  4096
 
 /* The core is safe for this COW optimisation. XS code on CPAN may not be.
    So only default to doing the COW setup if we're in the core.
@@ -1759,6 +1757,7 @@ mg.c:1024: warning: left-hand operand of comma expression has no effect
 #define sv_pvbyte(sv) SvPVbyte_nolen(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_catpvn_nomg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, 0)
 #define sv_setsv(dsv, ssv) \
@@ -2001,6 +2000,9 @@ Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
        }                                                               \
     } STMT_END
 #endif
+
+#define newIO()        MUTABLE_IO(newSV_type(SVt_PVIO))
+
 /*
  * Local variables:
  * c-indentation-style: bsd