This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
utf8.h: Add assertions for macros that take chars
[perl5.git] / sv.h
diff --git a/sv.h b/sv.h
index e311ff2..51e9b0b 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -155,7 +155,10 @@ typedef enum {
 /* *** 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 0xf0 are CURRENTLY UNUSED, except that 0xFF means a
+ * freed SV.  The bits above that are for flags, like SVf_IOK */
 
 #define SVt_MASK 0xf   /* smallest bitmask that covers all types */
 
@@ -538,7 +541,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
@@ -1517,43 +1521,58 @@ Like C<SvPV> but doesn't set a length variable.
 Like C<SvPV_nolen> but doesn't process magic.
 
 =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.
+Coerces the given SV to IV and returns 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).
+
+See C<L</SvIVx>> for a version which guarantees to evaluate C<sv> only once.
 
 =for apidoc Am|IV|SvIV_nomg|SV* sv
 Like C<SvIV> but doesn't process magic.
 
 =for apidoc Am|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>.
+Coerces the given SV to IV and returns 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).
+
+This form 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>.
 
 =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.
+Coerces the given SV to NV and returns 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).
+
+See C<L</SvNVx>> for a version which guarantees to evaluate C<sv> only once.
 
 =for apidoc Am|NV|SvNV_nomg|SV* sv
 Like C<SvNV> but doesn't process magic.
 
 =for apidoc Am|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>.
+Coerces the given SV to NV and returns 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).
+
+This form 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>.
 
 =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.
+Coerces the given SV to UV and returns 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).
+
+See C<L</SvUVx>> for a version which guarantees to evaluate C<sv> only once.
 
 =for apidoc Am|UV|SvUV_nomg|SV* sv
 Like C<SvUV> but doesn't process magic.
 
 =for apidoc Am|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>.
+Coerces the given SV to UV and returns 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).
+
+This form 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>.
 
 =for apidoc Am|bool|SvTRUE|SV* sv
 Returns a boolean indicating whether Perl would evaluate the SV as true or
@@ -2013,6 +2032,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.