Upgrade to podlators-2.2.0

[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index b3a23bc..0738dfb 100644 (file)
--- 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>
 
@@ -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>