utf8_to_bytes_: Add argument, macro

The argument is currently unused.  The macro is a public facing API that
calls this function with the correct argument

Author: khwilliamson

embed.fnc

@@ -3699,6 +3699,10 @@ CDbdp	|UV	|utf8n_to_uvuni |NN const U8 *s 			\
 Adpx	|U8 *	|utf8_to_bytes	|NN U8 *s				\
 				|NN STRLEN *lenp
 Cp	|bool	|utf8_to_bytes_ |NN U8 **s_ptr				\
+				|NN STRLEN *lenp			\
+				|Perl_utf8_to_bytes_arg result_as
+Admp	|bool	|utf8_to_bytes_overwrite				\
+				|NN U8 **s_ptr				\
 				|NN STRLEN *lenp
 EMXp	|U8 *	|utf16_to_utf8	|NN U8 *p				\
 				|NN U8 *d				\

embed.h

@@ -859,7 +859,8 @@
 # define utf8_hop_safe                          Perl_utf8_hop_safe
 # define utf8_length(a,b)                       Perl_utf8_length(aTHX_ a,b)
 # define utf8_to_bytes(a,b)                     Perl_utf8_to_bytes(aTHX_ a,b)
-# define utf8_to_bytes_(a,b)                    Perl_utf8_to_bytes_(aTHX_ a,b)
+# define utf8_to_bytes_(a,b,c)                  Perl_utf8_to_bytes_(aTHX_ a,b,c)
+# define utf8_to_bytes_overwrite(a,b)           Perl_utf8_to_bytes_overwrite(aTHX,a,b)
 # define utf8_to_uvchr_buf_helper(a,b,c)        Perl_utf8_to_uvchr_buf_helper(aTHX_ a,b,c)
 # define utf8n_to_uvchr_msgs                    Perl_utf8n_to_uvchr_msgs
 # define uvchr_to_utf8(a,b)                     Perl_uvchr_to_utf8(aTHX,a,b)

proto.h

@@ -2378,7 +2378,8 @@ If you need a copy of the string, see L</bytes_from_utf8>.
 */
 
 bool
-Perl_utf8_to_bytes_(pTHX_ U8 **s_ptr, STRLEN *lenp)
+Perl_utf8_to_bytes_(pTHX_ U8 **s_ptr, STRLEN *lenp,
+                          Perl_utf8_to_bytes_arg result_as)
 {
     PERL_ARGS_ASSERT_UTF8_TO_BYTES_;
     PERL_UNUSED_CONTEXT;
@@ -2597,7 +2598,7 @@ Perl_utf8_to_bytes(pTHX_ U8 *s, STRLEN *lenp)
 {
     PERL_ARGS_ASSERT_UTF8_TO_BYTES;
 
-    if (utf8_to_bytes_(&s, lenp)) {
+    if (utf8_to_bytes_overwrite(&s, lenp)) {
         return s;
     }
 

utf8.c

@@ -1306,6 +1306,15 @@ point's representation.
 
 #define Perl_is_utf8_char_buf(buf, buf_end) isUTF8_CHAR(buf, buf_end)
 
+typedef enum {
+    PL_utf8_to_bytes_overwrite = 0,
+    PL_utf8_to_bytes_new_memory,
+    PL_utf8_to_bytes_use_temporary,
+} Perl_utf8_to_bytes_arg;
+
+#define Perl_utf8_to_bytes_overwrite(mTHX, s, l)                            \
+        Perl_utf8_to_bytes_(aTHX_ s, l, PL_utf8_to_bytes_overwrite)
+
 /* Do not use; should be deprecated.  Use isUTF8_CHAR() instead; this is
  * retained solely for backwards compatibility */
 #define IS_UTF8_CHAR(p, n)      (isUTF8_CHAR(p, (p) + (n)) == n)