Upgrade to version.pm 0.71, by John Peacock

[perl5.git] / pod / perlapi.pod

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 106839d..7f82d8b 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -610,7 +610,7 @@ without it we only clone the data and zero the stacks,
 with it we copy the stacks and the new perl interpreter is
 ready to run at the exact same point as the previous one.
 The pseudo-fork code uses COPY_STACKS while the
-threads->new doesn't.
+threads->create doesn't.
 
 CLONEf_KEEP_PTR_TABLE
 perl_clone keeps a ptr_table with the pointer of the old
@@ -2535,12 +2535,12 @@ an RV.
 Function must be called with an already existing SV like
 
     sv = newSV(0);
-    s = scan_version(s,SV *sv, bool qv);
+    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 alpha version).  The boolean qv denotes that the version
+is an alpha version).  The boolean qv denotes that the version
 should be interpreted as if it had multiple decimals, even if
 it doesn't.
 
@@ -2656,11 +2656,12 @@ X<upg_version>
 
 In-place upgrade of the supplied SV to a version object.
 
-    SV *sv = upg_version(SV *sv);
+    SV *sv = upg_version(SV *sv, bool qv);
 
-Returns a pointer to the upgraded SV.
+Returns a pointer to the upgraded SV.  Set the boolean qv if you want
+to force this SV to be interpreted as an "extended" version.
 
-       SV*     upg_version(SV *ver)
+       SV*     upg_version(SV *ver, bool qv)
 
 =for hackers
 Found in file util.c
@@ -2913,6 +2914,37 @@ number may use '_' characters to separate digits.
 =for hackers
 Found in file numeric.c
 
+=item Perl_signbit
+X<Perl_signbit>
+
+Return a non-zero integer if the sign bit on an NV is set, and 0 if
+it is not.  
+
+If Configure detects this system has a signbit() that will work with
+our NVs, then we just use it via the #define in perl.h.  Otherwise,
+fall back on this implementation.  As a first pass, this gets everything
+right except -0.0.  Alas, catching -0.0 is the main use for this function,
+so this is not too helpful yet.  Still, at least we have the scaffolding
+in place to support other systems, should that prove useful.
+
+
+Configure notes:  This function is called 'Perl_signbit' instead of a
+plain 'signbit' because it is easy to imagine a system having a signbit()
+function or macro that doesn't happen to work with our particular choice
+of NVs.  We shouldn't just re-#define signbit as Perl_signbit and expect
+the standard system headers to be happy.  Also, this is a no-context
+function (no pTHX_) because Perl_signbit() is usually re-#defined in
+perl.h as a simple macro call to the system's signbit().
+Users should just always call Perl_signbit().
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+       int     Perl_signbit(NV f)
+
+=for hackers
+Found in file numeric.c
+
 =item scan_bin
 X<scan_bin>
 
@@ -5034,6 +5066,17 @@ The reference count for the SV is set to 1.
 =for hackers
 Found in file sv.c
 
+=item newSV_type
+X<newSV_type>
+
+Creates a new SV, of the type specificied.  The reference count for the new SV
+is set to 1.
+
+       SV*     newSV_type(svtype type)
+
+=for hackers
+Found in file sv.c
+
 =item sv_2bool
 X<sv_2bool>
 
@@ -5371,7 +5414,7 @@ X<sv_copypv>
 Copies a stringified representation of the source SV into the
 destination SV.  Automatically performs any necessary mg_get and
 coercion of numeric values into strings.  Guaranteed to preserve
-UTF-8 flag even from overloaded objects.  Similar in nature to
+UTF8 flag even from overloaded objects.  Similar in nature to
 sv_2pv[_flags] but operates directly on an SV instead of just the
 string.  Mostly uses sv_2pv_flags to do its work, except when that
 would lose the UTF-8'ness of the PV.