byte-order modifiers for (un)pack templates

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

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 5c0bee4..91da7ae 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -120,7 +120,8 @@ Found in file av.c
 =item av_delete
 
 Deletes the element indexed by C<key> from the array.  Returns the
-deleted element. C<flags> is currently ignored.
+deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
+and null is returned.
 
        SV*     av_delete(AV* ar, I32 key, I32 flags)
 
@@ -1772,15 +1773,17 @@ an RV.
 
 Function must be called with an already existing SV like
 
-    sv = NEWSV(92,0);
-    s = scan_version(s,sv);
+    sv = newSV(0);
+    s = scan_version(s,SV *sv, bool qv);
 
 Performs some preprocessing to the string to ensure that
 it has the correct characteristics of a version.  Flags the
 object if it contains an underscore (which denotes this
-is a beta version).
+is a alpha version).  The boolean qv denotes that the version
+should be interpreted as if it had multiple decimals, even if
+it doesn't.
 
-       char*   scan_version(char *vstr, SV *sv)
+       char*   scan_version(char *vstr, SV *sv, bool qv)
 
 =for hackers
 Found in file util.c
@@ -1922,6 +1925,21 @@ converted into version objects.
 =for hackers
 Found in file util.c
 
+=item vnormal
+
+Accepts a version object and returns the normalized string
+representation.  Call like:
+
+    sv = vnormal(rv);
+
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+
+       SV*     vnormal(SV *vs)
+
+=for hackers
+Found in file util.c
+
 =item vnumify
 
 Accepts a version object and returns the normalized floating
@@ -1939,13 +1957,10 @@ Found in file util.c
 
 =item vstringify
 
-Accepts a version object and returns the normalized string
-representation.  Call like:
-
-    sv = vstringify(rv);
-
-NOTE: you can pass either the object directly or the SV
-contained within the RV.
+In order to maintain maximum compatibility with earlier versions
+of Perl, this function will return either the floating point
+notation or the multiple dotted notation, depending on whether
+the original version contained 1 or more dots, respectively
 
        SV*     vstringify(SV *vs)
 
@@ -2822,7 +2837,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains a signed integer.
 
-       void    SvIOK_notUV(SV* sv)
+       bool    SvIOK_notUV(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2867,7 +2882,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains an unsigned integer.
 
-       void    SvIOK_UV(SV* sv)
+       bool    SvIOK_UV(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -3464,7 +3479,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
 
-       void    SvUTF8(SV* sv)
+       bool    SvUTF8(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -5398,8 +5413,9 @@ Found in file XSUB.h
 =item croak
 
 This is the XSUB-writer's interface to Perl's C<die> function.
-Normally use this function the same way you use the C C<printf>
-function.  See C<warn>.
+Normally call this function the same way you call the C C<printf>
+function.  Calling C<croak> returns control directly to Perl,
+sidestepping the normal C order of execution. See C<warn>.
 
 If you want to throw an exception object, assign the object to
 C<$@> and then pass C<Nullch> to croak():
@@ -5415,9 +5431,8 @@ Found in file util.c
 
 =item warn
 
-This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
-function the same way you use the C C<printf> function.  See
-C<croak>.
+This is the XSUB-writer's interface to Perl's C<warn> function.  Call this
+function the same way you call the C C<printf> function.  See C<croak>.
 
        void    warn(const char* pat, ...)