X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=0738dfbf73b4d3dc7b2e6a3065cd4b8d32f54a39;hb=9f2f055aa1e8c86d97b5ea42473ab1747f518f3a;hp=26420dedf35b39aafa817e32e2f9a17c857b4502;hpb=12964ddd5d77e0f02593286e5ca100221b0f8c59;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 26420de..0738dfb 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -237,7 +237,7 @@ X<av_len>
 Returns the highest index in the array.  The number of elements in the
 array is C<av_len(av) + 1>.  Returns -1 if the array is empty.
 
-	I32	av_len(const AV *av)
+	I32	av_len(AV *av)
 
 =for hackers
 Found in file av.c
@@ -279,7 +279,8 @@ Found in file av.c
 =item av_shift
 X<av_shift>
 
-Shifts an SV off the beginning of the array.
+Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the 
+array is empty.
 
 	SV*	av_shift(AV *av)
 
@@ -835,9 +836,6 @@ Found in file dump.c
 =item pv_escape
 X<pv_escape>
 
-               |const STRLEN count|const STRLEN max
-               |STRLEN const *escaped, const U32 flags
-
 Escapes at most the first "count" chars of pv and puts the results into
 dsv such that the size of the escaped string will not exceed "max" chars
 and will not contain any incomplete escape sequences.
@@ -872,8 +870,6 @@ sequences, whereas '%' is not a particularly common character in patterns.
 
 Returns a pointer to the escaped text as held by dsv.
 
-NOTE: the perl_ form of this function is deprecated.
-
 	char*	pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
 
 =for hackers
@@ -882,10 +878,6 @@ Found in file dump.c
 =item pv_pretty
 X<pv_pretty>
 
-           |const STRLEN count|const STRLEN max\
-           |const char const *start_color| const char const *end_color\
-           |const U32 flags
-
 Converts a string into something presentable, handling escaping via
 pv_escape() and supporting quoting and ellipses.
 
@@ -905,8 +897,6 @@ any quotes or ellipses.
 
 Returns a pointer to the prettified text as held by dsv.
            
-NOTE: the perl_ form of this function is deprecated.
-
 	char*	pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
 
 =for hackers
@@ -3931,6 +3921,23 @@ Found in file sv.h
 
 =over 8
 
+=item croak_xs_usage
+X<croak_xs_usage>
+
+A specialised variant of C<croak()> for emitting the usage message for xsubs
+
+    croak_xs_usage(cv, "eee_yow");
+
+works out the package name and subroutine name from C<cv>, and then calls
+C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
+
+    Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
+
+	void	croak_xs_usage(const CV *const cv, const char *const params)
+
+=for hackers
+Found in file universal.c
+
 =item get_sv
 X<get_sv>
 
@@ -5488,7 +5495,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 +5505,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 +5762,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>
 
@@ -6066,7 +6083,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 +6093,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 +6104,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 +6114,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
@@ -6301,7 +6318,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
@@ -6339,7 +6356,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 +6365,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 +6493,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 +6509,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 +6521,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 +6534,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 +6547,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 +6559,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