str

Copies the string's contents back and forth between the JavaScript garbage-collected heap and the Wasm linear memory with TextDecoder and TextEncoder. If you don't want to perform this copy, and would rather work with handles to JavaScript string values, use the js_sys::JsString type.

Example Rust Usage

# #![allow(unused_variables)]
#fn main() {
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn take_str_by_shared_ref(x: &str) {}

#}

Example JavaScript Usage

import {
  take_str_by_shared_ref,
} from './guide_supported_types_examples';

take_str_by_shared_ref('hello');

UTF-16 vs UTF-8

Strings in JavaScript are encoded as UTF-16, but with one major exception: they can contain unpaired surrogates. For some Unicode characters UTF-16 uses two 16-bit values. These are called "surrogate pairs" because they always come in pairs. In JavaScript, it is possible for these surrogate pairs to be missing the other half, creating an "unpaired surrogate".

When passing a string from JavaScript to Rust, it uses the TextEncoder API to convert from UTF-16 to UTF-8. This is normally perfectly fine... unless there are unpaired surrogates. In that case it will replace the unpaired surrogates with U+FFFD (�, the replacement character). That means the string in Rust is now different from the string in JavaScript!

If you want to guarantee that the Rust string is the same as the JavaScript string, you should instead use js_sys::JsString (which keeps the string in JavaScript and doesn't copy it into Rust).

If you want to access the raw value of a JS string, you can use JsString::iter, which returns an Iterator<Item = u16>. This perfectly preserves everything (including unpaired surrogates), but it does not do any encoding (so you have to do that yourself!).

If you simply want to ignore strings which contain unpaired surrogates, you can use JsString::is_valid_utf16 to test whether the string contains unpaired surrogates or not.