adding the newSVpvn API function

p4raw-id: //depot/perl@473

2 files changed, 21 insertions, 12 deletions

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 1aea1d8098..7a09d0d33c 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -34,11 +34,12 @@ An SV can be created and loaded with one command.  There are four types of
 values that can be loaded: an integer value (IV), a double (NV), a string,
 (PV), and another scalar (SV).
 
-The five routines are:
+The six routines are:
 
     SV*  newSViv(IV);
     SV*  newSVnv(double);
     SV*  newSVpv(char*, int);
+    SV*  newSVpvn(char*, int);
     SV*  newSVpvf(const char*, ...);
     SV*  newSVsv(SV*);
 
@@ -53,14 +54,14 @@ To change the value of an *already-existing* SV, there are seven routines:
     void  sv_setsv(SV*, SV*);
 
 Notice that you can choose to specify the length of the string to be
-assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to
-calculate the length by using C<sv_setpv> or by specifying 0 as the second
-argument to C<newSVpv>.  Be warned, though, that Perl will determine the
-string's length by using C<strlen>, which depends on the string terminating
-with a NUL character.  The arguments of C<sv_setpvf> are processed like
-C<sprintf>, and the formatted output becomes the value.  The C<sv_set*()>
-functions are not generic enough to operate on values that have "magic".
-See L<Magic Virtual Tables> later in this document.
+assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
+allow Perl to calculate the length by using C<sv_setpv> or by specifying
+0 as the second argument to C<newSVpv>.  Be warned, though, that Perl will
+determine the string's length by using C<strlen>, which depends on the
+string terminating with a NUL character.  The arguments of C<sv_setpvf>
+are processed like C<sprintf>, and the formatted output becomes the value.
+The C<sv_set*()> functions are not generic enough to operate on values
+that have "magic".  See L<Magic Virtual Tables> later in this document.
 
 All SVs that will contain strings should, but need not, be terminated
 with a NUL character.  If it is not NUL-terminated there is a risk of
@@ -2154,6 +2155,14 @@ SV is set to 1.  If C<len> is zero then Perl will compute the length.
 
 	SV*	newSVpv _((char* s, STRLEN len));
 
+=item newSVpvn
+
+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 then Perl will create a zero length 
+string.
+
+	SV*	newSVpvn _((char* s, STRLEN len));
+
 =item newSVrv
 
 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index 91de608d6c..d3f3a812b1 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -2420,9 +2420,9 @@ hv_iternext, hv_iternextsv, hv_iterval, hv_magic, HvNAME, hv_store,
 hv_store_ent, hv_undef, isALNUM, isALPHA, isDIGIT, isLOWER, isSPACE,
 isUPPER, items, ix, LEAVE, MARK, mg_clear, mg_copy, mg_find, mg_free,
 mg_get, mg_len, mg_magical, mg_set, Move, na, New, Newc, Newz, newAV,
-newHV, newRV_inc, newRV_noinc, NEWSV, newSViv, newSVnv, newSVpv, newSVrv,
-newSVsv, newXS, newXSproto, Nullav, Nullch, Nullcv, Nullhv, Nullsv,
-ORIGMARK, perl_alloc, perl_call_argv, perl_call_method, perl_call_pv,
+newHV, newRV_inc, newRV_noinc, NEWSV, newSViv, newSVnv, newSVpv, newSVpvn,
+newSVpvf, newSVrv, newSVsv, newXS, newXSproto, Nullav, Nullch, Nullcv, Nullhv,
+Nullsv, ORIGMARK, perl_alloc, perl_call_argv, perl_call_method, perl_call_pv,
 perl_call_sv, perl_construct, perl_destruct, perl_eval_sv, perl_eval_pv,
 perl_free, perl_get_av, perl_get_cv, perl_get_hv, perl_get_sv, perl_parse,
 perl_require_pv, perl_run, POPi, POPl, POPp, POPn, POPs, PUSHMARK, PUSHi,