pub struct JsString(/* private fields */);
Expand description
The type of JavaScript string primitives.
§Example
// Extract the console.log function:
let console: Handle<JsObject> = cx.global("console")?;
let log: Handle<JsFunction> = console.get(&mut cx, "log")?;
// Create a string:
let s = cx.string("hello 🥹");
// Call console.log(s):
log.call_with(&cx).arg(s).exec(&mut cx)?;
Implementations§
source§impl JsString
impl JsString
sourcepub fn size<'a, C: Context<'a>>(&self, cx: &mut C) -> usize
pub fn size<'a, C: Context<'a>>(&self, cx: &mut C) -> usize
Returns the size of the UTF-8 representation of this string, measured in 8-bit code units.
Equivalent to self.value(cx).len()
(but more efficient).
§Example
The string "hello 🥹"
encodes as 10 bytes in UTF-8:
- 6 bytes for
"hello "
(including the space). - 4 bytes for the emoji
"🥹"
.
let str = cx.string("hello 🥹");
assert_eq!(10, str.size(&mut cx));
sourcepub fn size_utf16<'a, C: Context<'a>>(&self, cx: &mut C) -> usize
pub fn size_utf16<'a, C: Context<'a>>(&self, cx: &mut C) -> usize
Returns the size of the UTF-16 representation of this string, measured in 16-bit code units.
Equivalent to self.to_utf16(cx).len()
(but more efficient).
§Example
The string "hello 🥹"
encodes as 8 code units in UTF-16:
- 6
u16
s for"hello "
(including the space). - 2
u16
s for the emoji"🥹"
.
let str = cx.string("hello 🥹");
assert_eq!(8, str.size_utf16(&mut cx));
sourcepub fn value<'a, C: Context<'a>>(&self, cx: &mut C) -> String
pub fn value<'a, C: Context<'a>>(&self, cx: &mut C) -> String
Convert this JavaScript string into a Rust String
.
§Example
This example function expects a single JavaScript string as argument and prints it out.
fn print_string(mut cx: FunctionContext) -> JsResult<JsUndefined> {
let s = cx.argument::<JsString>(0)?.value(&mut cx);
println!("JavaScript string contents: {}", s);
Ok(cx.undefined())
}
sourcepub fn to_utf16<'a, C: Context<'a>>(&self, cx: &mut C) -> Vec<u16>
pub fn to_utf16<'a, C: Context<'a>>(&self, cx: &mut C) -> Vec<u16>
Convert this JavaScript string into a Vec<u16>
encoded as UTF-16.
The returned vector is guaranteed to be valid UTF-16, so libraries that handle UTF-16-encoded strings can assume the content to be valid.
§Example
This example function expects a single JavaScript string as argument and prints it out
as a raw vector of u16
s.
fn print_string_as_utf16(mut cx: FunctionContext) -> JsResult<JsUndefined> {
let s = cx.argument::<JsString>(0)?.to_utf16(&mut cx);
println!("JavaScript string as raw UTF-16: {:?}", s);
Ok(cx.undefined())
}
This next example function also expects a single JavaScript string as argument and converts
to a Vec<u16>
, but utilizes the widestring
crate to handle the vector as a typical string.
use widestring::Utf16String;
fn print_with_widestring(mut cx: FunctionContext) -> JsResult<JsUndefined> {
let s = cx.argument::<JsString>(0)?.to_utf16(&mut cx);
// The returned vector is guaranteed to be valid UTF-16, so we can
// safely skip the validation step.
let s = unsafe { Utf16String::from_vec_unchecked(s) };
println!("JavaScript string as UTF-16: {}", s);
Ok(cx.undefined())
}
sourcepub fn new<'a, C: Context<'a>, S: AsRef<str>>(
cx: &mut C,
val: S
) -> Handle<'a, JsString>
pub fn new<'a, C: Context<'a>, S: AsRef<str>>( cx: &mut C, val: S ) -> Handle<'a, JsString>
Creates a new JsString
value from a Rust string by copying its contents.
This method panics if the string is longer than the maximum string size allowed by the JavaScript engine.
§Example
let str = JsString::new(&mut cx, "hello 🥹");
assert_eq!(10, str.size(&mut cx));
See also: Context::string
sourcepub fn try_new<'a, C: Context<'a>, S: AsRef<str>>(
cx: &mut C,
val: S
) -> StringResult<'a>
pub fn try_new<'a, C: Context<'a>, S: AsRef<str>>( cx: &mut C, val: S ) -> StringResult<'a>
Tries to create a new JsString
value from a Rust string by copying its contents.
Returns Err(StringOverflow)
if the string is longer than the maximum string size
allowed by the JavaScript engine.
§Example
This example tries to construct a JavaScript string from a Rust string of
unknown length, and on overflow generates an alternate truncated string with
a suffix ("[…]"
) to indicate the truncation.
let s = match JsString::try_new(&mut cx, str) {
Ok(s) => s,
Err(_) => cx.string(format!("{}[…]", &str[0..32])),
};