Document sv_vcatpvf, sv_vsetpvf, sv_vcatpvf_mg and sv_vsetpvf_mg.

These are already in the API supported by Devel::PPPort, and are
often more useful than sv_vcatpvfn and sv_vsetpvfn which were
already documented.

p4raw-id: //depot/perl@23368

diff --git a/embed.fnc b/embed.fnc
index 4b9a4a6..614e975 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -720,7 +720,7 @@ pd  |void   |sv_add_arena   |char* ptr|U32 size|U32 flags
 Apd    |int    |sv_backoff     |SV* sv
 Apd    |SV*    |sv_bless       |SV* sv|HV* stash
 Afpd   |void   |sv_catpvf      |SV* sv|const char* pat|...
-Ap     |void   |sv_vcatpvf     |SV* sv|const char* pat|va_list* args
+Apd    |void   |sv_vcatpvf     |SV* sv|const char* pat|va_list* args
 Apd    |void   |sv_catpv       |SV* sv|const char* ptr
 Amdb   |void   |sv_catpvn      |SV* sv|const char* ptr|STRLEN len
 Amdb   |void   |sv_catsv       |SV* dsv|SV* ssv
@@ -772,7 +772,7 @@ Apd |void   |sv_replace     |SV* sv|SV* nsv
 Apd    |void   |sv_report_used
 Apd    |void   |sv_reset       |char* s|HV* stash
 Afpd   |void   |sv_setpvf      |SV* sv|const char* pat|...
-Ap     |void   |sv_vsetpvf     |SV* sv|const char* pat|va_list* args
+Apd    |void   |sv_vsetpvf     |SV* sv|const char* pat|va_list* args
 Apd    |void   |sv_setiv       |SV* sv|IV num
 Apdb   |void   |sv_setpviv     |SV* sv|IV num
 Apd    |void   |sv_setuv       |SV* sv|UV num
@@ -872,12 +872,12 @@ Ap        |struct perl_vars *|GetVars
 Ap     |int    |runops_standard
 Ap     |int    |runops_debug
 Afpd   |void   |sv_catpvf_mg   |SV *sv|const char* pat|...
-Ap     |void   |sv_vcatpvf_mg  |SV* sv|const char* pat|va_list* args
+Apd    |void   |sv_vcatpvf_mg  |SV* sv|const char* pat|va_list* args
 Apd    |void   |sv_catpv_mg    |SV *sv|const char *ptr
 Apd    |void   |sv_catpvn_mg   |SV *sv|const char *ptr|STRLEN len
 Apd    |void   |sv_catsv_mg    |SV *dstr|SV *sstr
 Afpd   |void   |sv_setpvf_mg   |SV *sv|const char* pat|...
-Ap     |void   |sv_vsetpvf_mg  |SV* sv|const char* pat|va_list* args
+Apd    |void   |sv_vsetpvf_mg  |SV* sv|const char* pat|va_list* args
 Apd    |void   |sv_setiv_mg    |SV *sv|IV i
 Apdb   |void   |sv_setpviv_mg  |SV *sv|IV iv
 Apd    |void   |sv_setuv_mg    |SV *sv|UV u

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 8a4a12c..4de6b5e 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -3925,9 +3925,8 @@ Processes its arguments like C<sprintf> and appends the formatted
 output to an SV.  If the appended data contains "wide" characters
 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
 and characters >255 formatted with %c), the original SV might get
-upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.
-C<SvSETMAGIC()> must typically be called after calling this function
-to handle 'set' magic.
+upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
+C<sv_catpvf_mg>.
 
        void    sv_catpvf(SV* sv, const char* pat, ...)
 
@@ -4592,8 +4591,8 @@ Found in file sv.c
 
 =item sv_setpvf
 
-Processes its arguments like C<sprintf> and sets an SV to the formatted
-output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
+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, ...)
 
@@ -5000,6 +4999,18 @@ cope with complex macro expressions. Always use the macro instead.
 =for hackers
 Found in file sv.c
 
+=item sv_vcatpvf
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+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)
+
+=for hackers
+Found in file sv.c
+
 =item sv_vcatpvfn
 
 Processes its arguments like C<vsprintf> and appends the formatted output
@@ -5008,25 +5019,59 @@ missing (NULL).  When running with taint checks enabled, indicates via
 C<maybe_tainted> if results are untrustworthy (often due to the use of
 locales).
 
-Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
+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)
 
 =for hackers
 Found in file sv.c
 
+=item sv_vcatpvf_mg
+
+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)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvf
+
+Works like C<sv_vcatpvf> but copies the text into the SV instead of
+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)
+
+=for hackers
+Found in file sv.c
+
 =item sv_vsetpvfn
 
-Works like C<vcatpvfn> but copies the text into the SV instead of
+Works like C<sv_vcatpvfn> but copies the text into the SV instead of
 appending it.
 
-Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+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)
 
 =for hackers
 Found in file sv.c
 
+=item sv_vsetpvf_mg
+
+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)
+
+=for hackers
+Found in file sv.c
+
 
 =back
 

diff --git a/sv.c b/sv.c
index 5f91731..3fac004 100644 (file)
--- a/sv.c
+++ b/sv.c
@@ -8900,8 +8900,8 @@ Perl_sv_setpvf_mg_nocontext(SV *sv, const char* pat, ...)
 /*
 =for apidoc sv_setpvf
 
-Processes its arguments like C<sprintf> and sets an SV to the formatted
-output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
+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>.
 
 =cut
 */
@@ -8915,7 +8915,16 @@ Perl_sv_setpvf(pTHX_ SV *sv, const char* pat, ...)
     va_end(args);
 }
 
-/* backend for C<sv_setpvf> and C<sv_setpvf_nocontext> */
+/*
+=for apidoc sv_vsetpvf
+
+Works like C<sv_vcatpvf> but copies the text into the SV instead of
+appending it.  Does not handle 'set' magic.  See C<sv_vsetpvf_mg>.
+
+Usually used via its frontend C<sv_setpvf>.
+
+=cut
+*/
 
 void
 Perl_sv_vsetpvf(pTHX_ SV *sv, const char* pat, va_list* args)
@@ -8940,7 +8949,15 @@ Perl_sv_setpvf_mg(pTHX_ SV *sv, const char* pat, ...)
     va_end(args);
 }
 
-/* backend for C<sv_setpvf_mg> C<setpvf_mg_nocontext> */
+/*
+=for apidoc sv_vsetpvf_mg
+
+Like C<sv_vsetpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_setpvf_mg>.
+
+=cut
+*/
 
 void
 Perl_sv_vsetpvf_mg(pTHX_ SV *sv, const char* pat, va_list* args)
@@ -8989,9 +9006,8 @@ Processes its arguments like C<sprintf> and appends the formatted
 output to an SV.  If the appended data contains "wide" characters
 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
 and characters >255 formatted with %c), the original SV might get
-upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.
-C<SvSETMAGIC()> must typically be called after calling this function
-to handle 'set' magic.
+upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
+C<sv_catpvf_mg>.
 
 =cut */
 
@@ -9004,7 +9020,16 @@ Perl_sv_catpvf(pTHX_ SV *sv, const char* pat, ...)
     va_end(args);
 }
 
-/* backend for C<sv_catpvf> and C<catpvf_mg_nocontext> */
+/*
+=for apidoc sv_vcatpvf
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV.  Does not handle 'set' magic.  See C<sv_vcatpvf_mg>.
+
+Usually used via its frontend C<sv_catpvf>.
+
+=cut
+*/
 
 void
 Perl_sv_vcatpvf(pTHX_ SV *sv, const char* pat, va_list* args)
@@ -9029,7 +9054,15 @@ Perl_sv_catpvf_mg(pTHX_ SV *sv, const char* pat, ...)
     va_end(args);
 }
 
-/* backend for C<catpvf_mg> and C<catpvf_mg_nocontext> */
+/*
+=for apidoc sv_vcatpvf_mg
+
+Like C<sv_vcatpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_catpvf_mg>.
+
+=cut
+*/
 
 void
 Perl_sv_vcatpvf_mg(pTHX_ SV *sv, const char* pat, va_list* args)
@@ -9041,10 +9074,10 @@ Perl_sv_vcatpvf_mg(pTHX_ SV *sv, const char* pat, va_list* args)
 /*
 =for apidoc sv_vsetpvfn
 
-Works like C<vcatpvfn> but copies the text into the SV instead of
+Works like C<sv_vcatpvfn> but copies the text into the SV instead of
 appending it.
 
-Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
 
 =cut
 */
@@ -9109,7 +9142,7 @@ missing (NULL).  When running with taint checks enabled, indicates via
 C<maybe_tainted> if results are untrustworthy (often due to the use of
 locales).
 
-Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
+Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
 
 =cut
 */