perlunitut link
[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod
index c9ae52c..2644e88 100644 (file)
@@ -5108,7 +5108,7 @@ X<newRV_noinc>
 Creates an RV wrapper for an SV.  The reference count for the original
 SV is B<not> incremented.
 
-       SV*     newRV_noinc(SV* sv)
+       SV*     newRV_noinc(SV *const sv)
 
 =for hackers
 Found in file sv.c
@@ -5139,7 +5139,7 @@ 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)
+       SV*     newSVhek(const HEK *const hek)
 
 =for hackers
 Found in file sv.c
@@ -5150,7 +5150,7 @@ X<newSViv>
 Creates a new SV and copies an integer into it.  The reference count for the
 SV is set to 1.
 
-       SV*     newSViv(IV i)
+       SV*     newSViv(const IV i)
 
 =for hackers
 Found in file sv.c
@@ -5161,7 +5161,7 @@ X<newSVnv>
 Creates a new SV and copies a floating point value into it.
 The reference count for the SV is set to 1.
 
-       SV*     newSVnv(NV n)
+       SV*     newSVnv(const NV n)
 
 =for hackers
 Found in file sv.c
@@ -5173,7 +5173,7 @@ Creates a new SV and copies a string into it.  The reference count for the
 SV is set to 1.  If C<len> is zero, Perl will compute the length using
 strlen().  For efficiency, consider using C<newSVpvn> instead.
 
-       SV*     newSVpv(const char* s, STRLEN len)
+       SV*     newSVpv(const char *const s, const STRLEN len)
 
 =for hackers
 Found in file sv.c
@@ -5184,7 +5184,7 @@ X<newSVpvf>
 Creates a new SV and initializes it with the string formatted like
 C<sprintf>.
 
-       SV*     newSVpvf(const char* pat, ...)
+       SV*     newSVpvf(const char *const pat, ...)
 
 =for hackers
 Found in file sv.c
@@ -5197,7 +5197,7 @@ SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
 string.  You are responsible for ensuring that the source string is at least
 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
 
-       SV*     newSVpvn(const char* s, STRLEN len)
+       SV*     newSVpvn(const char *const s, const STRLEN len)
 
 =for hackers
 Found in file sv.c
@@ -5217,7 +5217,7 @@ C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
     #define newSVpvn_utf8(s, len, u)                   \
        newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
 
-       SV*     newSVpvn_flags(const char* s, STRLEN len, U32 flags)
+       SV*     newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)
 
 =for hackers
 Found in file sv.c
@@ -5278,7 +5278,7 @@ it will be upgraded to one.  If C<classname> is non-null then the new SV will
 be blessed in the specified package.  The new SV is returned and its
 reference count is 1.
 
-       SV*     newSVrv(SV* rv, const char* classname)
+       SV*     newSVrv(SV *const rv, const char *const classname)
 
 =for hackers
 Found in file sv.c
@@ -5289,7 +5289,7 @@ X<newSVsv>
 Creates a new SV which is an exact duplicate of the original SV.
 (Uses C<sv_setsv>).
 
-       SV*     newSVsv(SV* old)
+       SV*     newSVsv(SV *const old)
 
 =for hackers
 Found in file sv.c
@@ -5300,7 +5300,7 @@ X<newSVuv>
 Creates a new SV and copies an unsigned integer into it.
 The reference count for the SV is set to 1.
 
-       SV*     newSVuv(UV u)
+       SV*     newSVuv(const UV u)
 
 =for hackers
 Found in file sv.c
@@ -5334,7 +5334,7 @@ Using various gambits, try to get a CV from an SV; in addition, try if
 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
 The flags in C<lref> are passed to sv_fetchsv.
 
-       CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
+       CV*     sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
 
 =for hackers
 Found in file sv.c
@@ -5346,7 +5346,7 @@ Using various gambits, try to get an IO from an SV: the IO slot if its a
 GV; or the recursive result if we're an RV; or the IO slot of the symbol
 named after the PV if we're a string.
 
-       IO*     sv_2io(SV* sv)
+       IO*     sv_2io(SV *const sv)
 
 =for hackers
 Found in file sv.c
@@ -5372,7 +5372,7 @@ statement boundaries.  SvTEMP() is turned on which means that the SV's
 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
 and C<sv_mortalcopy>.
 
-       SV*     sv_2mortal(SV* sv)
+       SV*     sv_2mortal(SV *const sv)
 
 =for hackers
 Found in file sv.c
@@ -5460,7 +5460,7 @@ Blesses an SV into a specified package.  The SV must be an RV.  The package
 must be designated by its stash (see C<gv_stashpv()>).  The reference count
 of the SV is unaffected.
 
-       SV*     sv_bless(SV* sv, HV* stash)
+       SV*     sv_bless(SV *const sv, HV *const stash)
 
 =for hackers
 Found in file sv.c
@@ -5488,7 +5488,7 @@ upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
 valid UTF-8; if the original SV was bytes, the pattern should be too.
 
-       void    sv_catpvf(SV* sv, const char* pat, ...)
+       void    sv_catpvf(SV *const sv, const char *const pat, ...)
 
 =for hackers
 Found in file sv.c
@@ -5498,7 +5498,7 @@ X<sv_catpvf_mg>
 
 Like C<sv_catpvf>, but also handles 'set' magic.
 
-       void    sv_catpvf_mg(SV *sv, const char* pat, ...)
+       void    sv_catpvf_mg(SV *const sv, const char *const pat, ...)
 
 =for hackers
 Found in file sv.c
@@ -5755,13 +5755,23 @@ Found in file sv.c
 X<sv_insert>
 
 Inserts a string at the specified offset/length within the SV. Similar to
-the Perl substr() function.
+the Perl substr() function. Handles get magic.
 
        void    sv_insert(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen)
 
 =for hackers
 Found in file sv.c
 
+=item sv_insert_flags
+X<sv_insert_flags>
+
+Same as C<sv_insert>, but the extra C<flags> are passed the C<SvPV_force_flags> that applies to C<bigstr>.
+
+       void    sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)
+
+=for hackers
+Found in file sv.c
+
 =item sv_isa
 X<sv_isa>
 
@@ -5769,7 +5779,7 @@ Returns a boolean indicating whether the SV is blessed into the specified
 class.  This does not check for subtypes; use C<sv_derived_from> to verify
 an inheritance relationship.
 
-       int     sv_isa(SV* sv, const char* name)
+       int     sv_isa(SV* sv, const char *const name)
 
 =for hackers
 Found in file sv.c
@@ -5915,7 +5925,7 @@ X<sv_pvbyten_force>
 
 The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
 
-       char*   sv_pvbyten_force(SV* sv, STRLEN* lp)
+       char*   sv_pvbyten_force(SV *const sv, STRLEN *const lp)
 
 =for hackers
 Found in file sv.c
@@ -5942,7 +5952,7 @@ implemented in terms of this function.
 You normally want to use the various wrapper macros instead: see
 C<SvPV_force> and C<SvPV_force_nomg>
 
-       char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
+       char*   sv_pvn_force_flags(SV *const sv, STRLEN *const lp, const I32 flags)
 
 =for hackers
 Found in file sv.c
@@ -5952,7 +5962,7 @@ X<sv_pvutf8n_force>
 
 The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
 
-       char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
+       char*   sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
 
 =for hackers
 Found in file sv.c
@@ -5962,7 +5972,7 @@ X<sv_reftype>
 
 Returns a string describing what the SV is a reference to.
 
-       const char*     sv_reftype(const SV* sv, int ob)
+       const char*     sv_reftype(const SV *const sv, const int ob)
 
 =for hackers
 Found in file sv.c
@@ -5988,7 +5998,7 @@ X<sv_reset>
 Underlying implementation for the C<reset> Perl function.
 Note that the perl-level function is vaguely deprecated.
 
-       void    sv_reset(const char* s, HV* stash)
+       void    sv_reset(const char* s, HV *const stash)
 
 =for hackers
 Found in file sv.c
@@ -6066,7 +6076,7 @@ X<sv_setpvf>
 Works like C<sv_catpvf> but copies the text into the SV instead of
 appending it.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
 
-       void    sv_setpvf(SV* sv, const char* pat, ...)
+       void    sv_setpvf(SV *const sv, const char *const pat, ...)
 
 =for hackers
 Found in file sv.c
@@ -6076,7 +6086,7 @@ X<sv_setpvf_mg>
 
 Like C<sv_setpvf>, but also handles 'set' magic.
 
-       void    sv_setpvf_mg(SV *sv, const char* pat, ...)
+       void    sv_setpvf_mg(SV *const sv, const char *const pat, ...)
 
 =for hackers
 Found in file sv.c
@@ -6087,7 +6097,7 @@ X<sv_setpviv>
 Copies an integer into the given SV, also updating its string value.
 Does not handle 'set' magic.  See C<sv_setpviv_mg>.
 
-       void    sv_setpviv(SV* sv, IV num)
+       void    sv_setpviv(SV *const sv, const IV num)
 
 =for hackers
 Found in file sv.c
@@ -6097,7 +6107,7 @@ X<sv_setpviv_mg>
 
 Like C<sv_setpviv>, but also handles 'set' magic.
 
-       void    sv_setpviv_mg(SV *sv, IV iv)
+       void    sv_setpviv_mg(SV *const sv, const IV iv)
 
 =for hackers
 Found in file sv.c
@@ -6153,7 +6163,7 @@ the new SV.  The C<classname> argument indicates the package for the
 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
 will have a reference count of 1, and the RV will be returned.
 
-       SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
+       SV*     sv_setref_iv(SV *const rv, const char *const classname, const IV iv)
 
 =for hackers
 Found in file sv.c
@@ -6167,7 +6177,7 @@ the new SV.  The C<classname> argument indicates the package for the
 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
 will have a reference count of 1, and the RV will be returned.
 
-       SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
+       SV*     sv_setref_nv(SV *const rv, const char *const classname, const NV nv)
 
 =for hackers
 Found in file sv.c
@@ -6187,7 +6197,7 @@ objects will become corrupted by the pointer copy process.
 
 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
 
-       SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
+       SV*     sv_setref_pv(SV *const rv, const char *const classname, void *const pv)
 
 =for hackers
 Found in file sv.c
@@ -6204,7 +6214,7 @@ of 1, and the RV will be returned.
 
 Note that C<sv_setref_pv> copies the pointer while this copies the string.
 
-       SV*     sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n)
+       SV*     sv_setref_pvn(SV *const rv, const char *const classname, const char *const pv, const STRLEN n)
 
 =for hackers
 Found in file sv.c
@@ -6218,7 +6228,7 @@ the new SV.  The C<classname> argument indicates the package for the
 blessing.  Set C<classname> to C<NULL> to avoid the blessing.  The new SV
 will have a reference count of 1, and the RV will be returned.
 
-       SV*     sv_setref_uv(SV* rv, const char* classname, UV uv)
+       SV*     sv_setref_uv(SV *const rv, const char *const classname, const UV uv)
 
 =for hackers
 Found in file sv.c
@@ -6301,7 +6311,7 @@ Found in file sv.c
 X<sv_tainted>
 
 Test an SV for taintedness. Use C<SvTAINTED> instead.
-       bool    sv_tainted(SV* sv)
+       bool    sv_tainted(SV *const sv)
 
 =for hackers
 Found in file sv.c
@@ -6313,7 +6323,7 @@ Returns true if the SV has a true value by Perl's rules.
 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
 instead use an in-line version.
 
-       I32     sv_true(SV *sv)
+       I32     sv_true(SV *const sv)
 
 =for hackers
 Found in file sv.c
@@ -6339,7 +6349,7 @@ C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
 different from one or the reference being a readonly SV).
 See C<SvROK_off>.
 
-       void    sv_unref_flags(SV *ref, U32 flags)
+       void    sv_unref_flags(SV *const ref, const U32 flags)
 
 =for hackers
 Found in file sv.c
@@ -6348,7 +6358,7 @@ Found in file sv.c
 X<sv_untaint>
 
 Untaint an SV. Use C<SvTAINTED_off> instead.
-       void    sv_untaint(SV* sv)
+       void    sv_untaint(SV *const sv)
 
 =for hackers
 Found in file sv.c
@@ -6476,7 +6486,7 @@ to an SV.  Does not handle 'set' magic.  See C<sv_vcatpvf_mg>.
 
 Usually used via its frontend C<sv_catpvf>.
 
-       void    sv_vcatpvf(SV* sv, const char* pat, va_list* args)
+       void    sv_vcatpvf(SV *const sv, const char *const pat, va_list *const args)
 
 =for hackers
 Found in file sv.c
@@ -6492,7 +6502,7 @@ locales).
 
 Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
 
-       void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+       void    sv_vcatpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
 
 =for hackers
 Found in file sv.c
@@ -6504,7 +6514,7 @@ Like C<sv_vcatpvf>, but also handles 'set' magic.
 
 Usually used via its frontend C<sv_catpvf_mg>.
 
-       void    sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
+       void    sv_vcatpvf_mg(SV *const sv, const char *const pat, va_list *const args)
 
 =for hackers
 Found in file sv.c
@@ -6517,7 +6527,7 @@ appending it.  Does not handle 'set' magic.  See C<sv_vsetpvf_mg>.
 
 Usually used via its frontend C<sv_setpvf>.
 
-       void    sv_vsetpvf(SV* sv, const char* pat, va_list* args)
+       void    sv_vsetpvf(SV *const sv, const char *const pat, va_list *const args)
 
 =for hackers
 Found in file sv.c
@@ -6530,7 +6540,7 @@ appending it.
 
 Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
 
-       void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+       void    sv_vsetpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
 
 =for hackers
 Found in file sv.c
@@ -6542,7 +6552,7 @@ Like C<sv_vsetpvf>, but also handles 'set' magic.
 
 Usually used via its frontend C<sv_setpvf_mg>.
 
-       void    sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
+       void    sv_vsetpvf_mg(SV *const sv, const char *const pat, va_list *const args)
 
 =for hackers
 Found in file sv.c