Extend newSVpvn_flags() to also call sv_2mortal() if SVs_TEMP is set in

the flags. Move its implementation just ahead of sv_2mortal()'s for
CPU cache locality. Refactor all code that can be to use this.

p4raw-id: //depot/perl@32818

1 files changed, 4 insertions, 3 deletions

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 8546d4f6df..d9a2eebcd3 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -5173,9 +5173,10 @@ Creates a new SV and copies a string into it.  The reference count for the
 SV is set to 1.  Note that if C<len> is zero, Perl will create a zero length
 string.  You are responsible for ensuring that the source string is at least
 C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
-Currently the only flag bit accepted is SVf_UTF8. If this is set, then it
-will be set on the new SV. C<newSVpvn_utf8()> is a convenience wrapper for
-this function, defined as
+Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
+If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before
+returning. If C<SVf_UTF8> is set, then it will be set on the new SV.
+C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
 
     #define newSVpvn_utf8(s, len, u)			\
 	newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)