Change 24733 allows several pointers to be NULL. Therefore this
[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod
index 07319f2..86d97ff 100644 (file)
@@ -693,7 +693,7 @@ Found in file perl.c
 
 The engine implementing pack() Perl function.
 
-       void    packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist)
+       void    packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
 
 =for hackers
 Found in file pp_pack.c
@@ -703,7 +703,7 @@ Found in file pp_pack.c
 The engine implementing pack() Perl function. Note: parameters next_in_list and
 flags are not used. This call should not be used; use packlist instead.
 
-       void    pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
+       void    pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
 
 =for hackers
 Found in file pp_pack.c
@@ -714,7 +714,7 @@ The engine implementing unpack() Perl function. C<unpackstring> puts the
 extracted list items on the stack and returns the number of elements.
 Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
 
-       I32     unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags)
+       I32     unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
 
 =for hackers
 Found in file pp_pack.c
@@ -724,7 +724,7 @@ Found in file pp_pack.c
 The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
 and ocnt are not used. This call should not be used, use unpackstring instead.
 
-       I32     unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
+       I32     unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
 
 =for hackers
 Found in file pp_pack.c
@@ -2042,7 +2042,7 @@ C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
 number may use '_' characters to separate digits.
 
-       UV      grok_bin(const char* start, STRLEN* len, I32* flags, NV *result)
+       UV      grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
 
 =for hackers
 Found in file numeric.c
@@ -2070,7 +2070,7 @@ C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
 number may use '_' characters to separate digits.
 
-       UV      grok_hex(const char* start, STRLEN* len, I32* flags, NV *result)
+       UV      grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
 
 =for hackers
 Found in file numeric.c
@@ -2130,7 +2130,7 @@ is NULL).
 If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
 number may use '_' characters to separate digits.
 
-       UV      grok_oct(const char* start, STRLEN* len, I32* flags, NV *result)
+       UV      grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
 
 =for hackers
 Found in file numeric.c
@@ -2942,6 +2942,17 @@ macro.
 =for hackers
 Found in file sv.c
 
+=item newSVhek
+
+Creates a new SV from the hash key structure.  It will generate scalars that
+point to the shared string table where possible. Returns a new (undefined)
+SV if the hek is NULL.
+
+       SV*     newSVhek(const HEK *hek)
+
+=for hackers
+Found in file sv.c
+
 =item newSViv
 
 Creates a new SV and copies an integer into it.  The reference count for the
@@ -2997,12 +3008,12 @@ Found in file sv.c
 
 =item newSVpvn_share
 
-Creates a new SV with its SvPVX pointing to a shared string in the string
+Creates a new SV with its SvPVX_const pointing to a shared string in the string
 table. If the string does not already exist in the table, it is created
 first.  Turns on READONLY and FAKE.  The string's hash is stored in the UV
 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
 otherwise the hash is computed.  The idea here is that as the string table
-is used for shared hash keys these strings will have SvPVX == HeKEY and
+is used for shared hash keys these strings will have SvPVX_const == HeKEY and
 hash lookup will avoid string compare.
 
        SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
@@ -3053,7 +3064,8 @@ Found in file sv.h
 
 =item SvCUR_set
 
-Set the length of the string which is in the SV.  See C<SvCUR>.
+Set the current length of the string which is in the SV.  See C<SvCUR>
+and C<SvIV_set>.
 
        void    SvCUR_set(SV* sv, STRLEN len)
 
@@ -3215,6 +3227,18 @@ Like C<SvIV> but doesn't process magic.
 =for hackers
 Found in file sv.h
 
+=item SvIV_set
+
+Set the value of the IV pointer in sv to val.  It is possible to perform
+the same function of this macro with an lvalue assignment to C<SvIVX>.
+With future Perls, however, it will be more efficient to use 
+C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
+
+       void    SvIV_set(SV* sv, IV val)
+
+=for hackers
+Found in file sv.h
+
 =item SvLEN
 
 Returns the size of the string buffer in the SV, not including any part
@@ -3225,6 +3249,24 @@ attributable to C<SvOOK>.  See C<SvCUR>.
 =for hackers
 Found in file sv.h
 
+=item SvLEN_set
+
+Set the actual length of the string which is in the SV.  See C<SvIV_set>.
+
+       void    SvLEN_set(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvMAGIC_set
+
+Set the value of the MAGIC pointer in sv to val.  See C<SvIV_set>.
+
+       void    SvMAGIC_set(SV* sv, MAGIC* val)
+
+=for hackers
+Found in file sv.h
+
 =item SvNIOK
 
 Returns a boolean indicating whether the SV contains a number, integer or
@@ -3330,6 +3372,15 @@ sv only once. Use the more efficient C<SvNV> otherwise.
 =for hackers
 Found in file sv.h
 
+=item SvNV_set
+
+Set the value of the NV pointer in sv to val.  See C<SvIV_set>.
+
+       void    SvNV_set(SV* sv, NV val)
+
+=for hackers
+Found in file sv.h
+
 =item SvOK
 
 Returns a boolean indicating whether the value is an SV. It also tells
@@ -3581,6 +3632,15 @@ Like C<SvPV> but doesn't process magic.
 =for hackers
 Found in file sv.h
 
+=item SvPV_set
+
+Set the value of the PV pointer in sv to val.  See C<SvIV_set>.
+
+       void    SvPV_set(SV* sv, char* val)
+
+=for hackers
+Found in file sv.h
+
 =item SvREFCNT
 
 Returns the value of the object's reference count.
@@ -3644,6 +3704,15 @@ Dereferences an RV to return the SV.
 =for hackers
 Found in file sv.h
 
+=item SvRV_set
+
+Set the value of the RV pointer in sv to val.  See C<SvIV_set>.
+
+       void    SvRV_set(SV* sv, SV* val)
+
+=for hackers
+Found in file sv.h
+
 =item SvSTASH
 
 Returns the stash of the SV.
@@ -3653,6 +3722,15 @@ Returns the stash of the SV.
 =for hackers
 Found in file sv.h
 
+=item SvSTASH_set
+
+Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
+
+       void    SvSTASH_set(SV* sv, STASH* val)
+
+=for hackers
+Found in file sv.h
+
 =item SvTAINT
 
 Taints an SV if tainting is enabled.
@@ -3800,6 +3878,15 @@ Like C<SvUV> but doesn't process magic.
 =for hackers
 Found in file sv.h
 
+=item SvUV_set
+
+Set the value of the UV pointer in sv to val.  See C<SvIV_set>.
+
+       void    SvUV_set(SV* sv, UV val)
+
+=for hackers
+Found in file sv.h
+
 =item SvVOK
 
 Returns a boolean indicating whether the SV contains a v-string.
@@ -4113,10 +4200,10 @@ Efficient removal of characters from the beginning of the string buffer.
 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
 the string buffer.  The C<ptr> becomes the first character of the adjusted
 string. Uses the "OOK hack".
-Beware: after this function returns, C<ptr> and SvPVX(sv) may no longer
+Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
 refer to the same chunk of data.
 
-       void    sv_chop(SV* sv, char* ptr)
+       void    sv_chop(SV* sv, const char* ptr)
 
 =for hackers
 Found in file sv.c
@@ -4568,7 +4655,7 @@ Found in file sv.c
 
 Returns a string describing what the SV is a reference to.
 
-       const char*     sv_reftype(const SV* sv, int ob)
+       char*   sv_reftype(const SV* sv, int ob)
 
 =for hackers
 Found in file sv.c
@@ -5238,6 +5325,8 @@ UTF-8 string, false otherwise.  Note that 'a valid UTF-8 string' does
 not mean 'a string that contains code points above 0x7F encoded in UTF-8'
 because a valid ASCII string is a valid UTF-8 string.
 
+See also is_utf8_string_loclen() and is_utf8_string_loc().
+
        bool    is_utf8_string(const U8 *s, STRLEN len)
 
 =for hackers
@@ -5245,14 +5334,31 @@ Found in file utf8.c
 
 =item is_utf8_string_loc
 
-Like is_ut8_string but store the location of the failure in
-the last argument.
+Like is_ut8_string() but stores the location of the failure (in the
+case of "utf8ness failure") or the location s+len (in the case of
+"utf8ness success") in the C<ep>.
+
+See also is_utf8_string_loclen() and is_utf8_string().
 
        bool    is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
 
 =for hackers
 Found in file utf8.c
 
+=item is_utf8_string_loclen
+
+Like is_ut8_string() but stores the location of the failure (in the
+case of "utf8ness failure") or the location s+len (in the case of
+"utf8ness success") in the C<ep>, and the number of UTF-8
+encoded characters in the C<el>.
+
+See also is_utf8_string_loc() and is_utf8_string().
+
+       bool    is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
+
+=for hackers
+Found in file utf8.c
+
 =item pv_uni_display
 
 Build to the scalar dsv a displayable version of the string spv,
@@ -5471,7 +5577,7 @@ WARNING: do not use the following unless you *know* C<off> is within
 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
 on the first byte of character or just after the last byte of a character.
 
-       U8*     utf8_hop(U8 *s, I32 off)
+       U8*     utf8_hop(const U8 *s, I32 off)
 
 =for hackers
 Found in file utf8.c
@@ -5615,6 +5721,16 @@ This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
 =for hackers
 Found in file XSUB.h
 
+=item dAXMARK
+
+Sets up the C<ax> variable and stack marker variable C<mark>.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+               dAXMARK;
+
+=for hackers
+Found in file XSUB.h
+
 =item dITEMS
 
 Sets up the C<items> variable.