From: Steve Hay <SteveHay@planit.com>
Date: Fri, 15 Oct 2004 10:12:31 +0000 (+0000)
Subject: Document sv_vcatpvf, sv_vsetpvf, sv_vcatpvf_mg and sv_vsetpvf_mg.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=bffc3d176498c580e8c7f5c238edf3c2945b99be;p=p5sagit%2Fp5-mst-13.2.git
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
--- 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
--- 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
--- 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
*/