Move writeStringToMemory/writeAsciiToMemory to library_legacy.js (#19103)

`writeStringToMemory` was already marked as deprecated.

We have `stringToAscii` and `stringToUTF8` which we recommend over these
function.

Also, change `stringToUTF8Array` to `stringToUTF8` in a couple of places
here the target is `HEAPU8`.

Author: sbc100

site/source/docs/api_reference/preamble.js.rst

@@ -252,32 +252,6 @@ Conversion functions — strings, pointers and arrays
   :returns: A ``String``, containing the content of ``array``.
 
 
-
-.. js:function:: writeStringToMemory(string, buffer, dontAddNull)
-
-  Writes a JavaScript string to a specified address in the heap.
-
-  .. warning:: This function is deprecated, you should call the function ``stringToUTF8`` instead, which provides a secure bounded version of the same functionality instead.
-
-  .. code-block:: javascript
-
-    // Allocate space for string and extra '0' at the end
-    var buffer = Module._malloc(myString.length+1);
-
-    // Write the string to memory
-    Module.writeStringToMemory(myString, buffer);
-
-    // We can now send buffer into a C function, it is just a normal char* pointer
-
-  :param string: The string to write into memory.
-  :type string: String
-  :param buffer: The address (number) where ``string`` is to be written.
-  :type buffer: Number
-  :param dontAddNull: If ``true``, the new array is not zero-terminated.
-  :type dontAddNull: bool
-
-
-
 .. js:function:: writeArrayToMemory(array, buffer)
 
   Writes an array to a specified address in the heap. Note that memory should to be allocated for the array before it is written.
@@ -288,29 +262,8 @@ Conversion functions — strings, pointers and arrays
 
 
 
-.. js:function:: writeAsciiToMemory(str, buffer, dontAddNull)
-
-  Writes an ASCII string to a specified address in the heap. Note that memory should to be allocated for the string before it is written.
-
-  The string is assumed to only have characters in the ASCII character set. If ASSERTIONS are enabled and this is not the case, it will fail.
-
-  .. code-block:: javascript
-
-    // Allocate space for string
-    var buffer = Module._malloc(myString.length);
-
-    // Write the string to memory
-    Module.writeStringToMemory(myString, buffer);
-
-  :param string: The string to write into memory.
-  :param buffer: The address where ``string`` is to be written.
-  :param dontAddNull: If ``true``, the new string is not zero-terminated.
-  :type dontAddNull: bool
-
-
-
 Run dependencies
-=====================================
+================
 
 Note that generally run dependencies are managed by the file packager and other parts of the system. It is rare for developers to use this API directly.
 
@@ -338,7 +291,7 @@ Note that generally run dependencies are managed by the file packager and other
 
 
 Stack trace
-=====================
+===========
 
 .. js:function:: stackTrace()
 

src/library.js

@@ -2078,15 +2078,15 @@ mergeInto(LibraryManager.library, {
     list: [],
     map: {}
   },
-  setprotoent__deps: ['$Protocols', '$writeAsciiToMemory', 'malloc'],
+  setprotoent__deps: ['$Protocols', '$stringToAscii', 'malloc'],
   setprotoent: function(stayopen) {
     // void setprotoent(int stayopen);
 
     // Allocate and populate a protoent structure given a name, protocol number and array of aliases
     function allocprotoent(name, proto, aliases) {
       // write name into buffer
       var nameBuf = _malloc(name.length + 1);
-      writeAsciiToMemory(name, nameBuf);
+      stringToAscii(name, nameBuf);
 
       // write aliases into buffer
       var j = 0;
@@ -2096,7 +2096,7 @@ mergeInto(LibraryManager.library, {
       for (var i = 0; i < length; i++, j += 4) {
         var alias = aliases[i];
         var aliasBuf = _malloc(alias.length + 1);
-        writeAsciiToMemory(alias, aliasBuf);
+        stringToAscii(alias, aliasBuf);
         {{{ makeSetValue('aliasListBuf', 'j', 'aliasBuf', POINTER_TYPE) }}};
       }
       {{{ makeSetValue('aliasListBuf', 'j', '0', POINTER_TYPE) }}}; // Terminating NULL pointer.

src/library_legacy.js

@@ -38,6 +38,40 @@ mergeInto(LibraryManager.library, {
     return ret;
   },
 
+  // Deprecated: This function should not be called because it is unsafe and
+  // does not provide a maximum length limit of how many bytes it is allowed to
+  // write. Prefer calling the function stringToUTF8Array() instead, which takes
+  // in a maximum length that can be used to be secure from out of bounds
+  // writes.
+  $writeStringToMemory__docs: '/** @deprecated @param {boolean=} dontAddNull */',
+  $writeStringToMemory: function(string, buffer, dontAddNull) {
+    warnOnce('writeStringToMemory is deprecated and should not be called! Use stringToUTF8() instead!');
+
+    var /** @type {number} */ lastChar, /** @type {number} */ end;
+    if (dontAddNull) {
+      // stringToUTF8Array always appends null. If we don't want to do that, remember the
+      // character that existed at the location where the null will be placed, and restore
+      // that after the write (below).
+      end = buffer + lengthBytesUTF8(string);
+      lastChar = HEAP8[end];
+    }
+    stringToUTF8(string, buffer, Infinity);
+    if (dontAddNull) HEAP8[end] = lastChar; // Restore the value under the null character.
+  },
+
+  // Deprecated: Use stringToAscii
+  $writeAsciiToMemory__docs: '/** @param {boolean=} dontAddNull */',
+  $writeAsciiToMemory: function(str, buffer, dontAddNull) {
+    for (var i = 0; i < str.length; ++i) {
+#if ASSERTIONS
+      assert(str.charCodeAt(i) === (str.charCodeAt(i) & 0xff));
+#endif
+      {{{ makeSetValue('buffer++', 0, 'str.charCodeAt(i)', 'i8') }}};
+    }
+    // Null-terminate the string
+    if (!dontAddNull) {{{ makeSetValue('buffer', 0, 0, 'i8') }}};
+  },
+
   $allocateUTF8: '$stringToNewUTF8',
   $allocateUTF8OnStack: '$stringToUTF8OnStack',
 });

src/library_strings.js

@@ -29,9 +29,15 @@ mergeInto(LibraryManager.library, {
   // Copies the given Javascript String object 'str' to the emscripten HEAP at
   // address 'outPtr', null-terminated and encoded in ASCII form. The copy will
   // require at most str.length+1 bytes of space in the HEAP.
-  $stringToAscii__deps: ['$writeAsciiToMemory'],
-  $stringToAscii: function(str, outPtr) {
-    return writeAsciiToMemory(str, outPtr, false);
+  $stringToAscii: function(str, buffer) {
+    for (var i = 0; i < str.length; ++i) {
+#if ASSERTIONS
+      assert(str.charCodeAt(i) === (str.charCodeAt(i) & 0xff));
+#endif
+      {{{ makeSetValue('buffer++', 0, 'str.charCodeAt(i)', 'i8') }}};
+    }
+    // Null-terminate the string
+    {{{ makeSetValue('buffer', 0, 0, 'i8') }}};
   },
 
 #if TEXTDECODER == 2
@@ -229,55 +235,22 @@ mergeInto(LibraryManager.library, {
   $stringToNewUTF8: function(str) {
     var size = lengthBytesUTF8(str) + 1;
     var ret = {{{ makeMalloc('stringToNewUTF8', 'size') }}};
-    if (ret) stringToUTF8Array(str, HEAP8, ret, size);
+    if (ret) stringToUTF8(str, ret, size);
     return ret;
   },
 
   // Allocate stack space for a JS string, and write it there.
   $stringToUTF8OnStack: function(str) {
     var size = lengthBytesUTF8(str) + 1;
     var ret = stackAlloc(size);
-    stringToUTF8Array(str, HEAP8, ret, size);
+    stringToUTF8(str, ret, size);
     return ret;
   },
 
-  // Deprecated: This function should not be called because it is unsafe and
-  // does not provide a maximum length limit of how many bytes it is allowed to
-  // write. Prefer calling the function stringToUTF8Array() instead, which takes
-  // in a maximum length that can be used to be secure from out of bounds
-  // writes.
-  $writeStringToMemory__docs: '/** @deprecated @param {boolean=} dontAddNull */',
-  $writeStringToMemory: function(string, buffer, dontAddNull) {
-    warnOnce('writeStringToMemory is deprecated and should not be called! Use stringToUTF8() instead!');
-
-    var /** @type {number} */ lastChar, /** @type {number} */ end;
-    if (dontAddNull) {
-      // stringToUTF8Array always appends null. If we don't want to do that, remember the
-      // character that existed at the location where the null will be placed, and restore
-      // that after the write (below).
-      end = buffer + lengthBytesUTF8(string);
-      lastChar = HEAP8[end];
-    }
-    stringToUTF8(string, buffer, Infinity);
-    if (dontAddNull) HEAP8[end] = lastChar; // Restore the value under the null character.
-  },
-
   $writeArrayToMemory: function(array, buffer) {
 #if ASSERTIONS
     assert(array.length >= 0, 'writeArrayToMemory array must have a length (should be an array or typed array)')
 #endif
     HEAP8.set(array, buffer);
   },
-
-  $writeAsciiToMemory__docs: '/** @param {boolean=} dontAddNull */',
-  $writeAsciiToMemory: function(str, buffer, dontAddNull) {
-    for (var i = 0; i < str.length; ++i) {
-#if ASSERTIONS
-      assert(str.charCodeAt(i) === (str.charCodeAt(i) & 0xff));
-#endif
-      {{{ makeSetValue('buffer++', 0, 'str.charCodeAt(i)', 'i8') }}};
-    }
-    // Null-terminate the pointer to the HEAP.
-    if (!dontAddNull) {{{ makeSetValue('buffer', 0, 0, 'i8') }}};
-  },
 });

src/library_wasi.js

@@ -87,14 +87,14 @@ var WasiLibrary = {
     return 0;
   },
 
-  environ_get__deps: ['$getEnvStrings', '$writeAsciiToMemory'],
+  environ_get__deps: ['$getEnvStrings', '$stringToAscii'],
   environ_get__nothrow: true,
   environ_get: function(__environ, environ_buf) {
     var bufSize = 0;
     getEnvStrings().forEach(function(string, i) {
       var ptr = environ_buf + bufSize;
       {{{ makeSetValue('__environ', `i*${POINTER_SIZE}`, 'ptr', POINTER_TYPE) }}};
-      writeAsciiToMemory(string, ptr);
+      stringToAscii(string, ptr);
       bufSize += string.length + 1;
     });
     return 0;
@@ -119,14 +119,14 @@ var WasiLibrary = {
   },
 
   args_get__nothrow: true,
-  args_get__deps: ['$writeAsciiToMemory'],
+  args_get__deps: ['$stringToAscii'],
   args_get: function(argv, argv_buf) {
 #if MAIN_READS_PARAMS
     var bufSize = 0;
     mainArgs.forEach(function(arg, i) {
       var ptr = argv_buf + bufSize;
       {{{ makeSetValue('argv', `i*${POINTER_SIZE}`, 'ptr', POINTER_TYPE) }}};
-      writeAsciiToMemory(arg, ptr);
+      stringToAscii(arg, ptr);
       bufSize += arg.length + 1;
     });
 #endif

test/other/metadce/test_metadce_hello_dylink.jssize

@@ -1 +1 @@
-27921
+27922

test/other/metadce/test_metadce_mem_O3_grow.jssize

@@ -1 +1 @@
-6436
+6429

test/other/test_unoptimized_code_size_strict.js.size

@@ -1 +1 @@
-63435
+63386

test/test_core.py

@@ -5887,11 +5887,11 @@ def test_utf32(self):
 
   @crossplatform
   def test_utf16(self):
-    self.set_setting('EXPORTED_RUNTIME_METHODS', ['writeAsciiToMemory', 'UTF16ToString', 'stringToUTF16'])
+    self.set_setting('EXPORTED_RUNTIME_METHODS', ['UTF16ToString', 'stringToUTF16'])
     self.do_runf(test_file('core/test_utf16.cpp'), 'OK.')
 
   def test_utf8(self):
-    self.set_setting('EXPORTED_RUNTIME_METHODS', ['UTF8ToString', 'stringToUTF8', 'AsciiToString', 'stringToAscii', 'writeAsciiToMemory'])
+    self.set_setting('EXPORTED_RUNTIME_METHODS', ['UTF8ToString', 'stringToUTF8', 'AsciiToString', 'stringToAscii'])
     self.do_runf(test_file('utf8.cpp'), 'OK.')
 
   @also_with_wasm_bigint