Struct String

#[repr(C)]
pub struct String(/* private fields */);

A JavaScript string value (ECMA-262, 4.3.17).

Implementations

impl String

pub const MAX_LENGTH: usize = 536_870_888usize

The maximum length (in bytes) of a buffer that a v8::String can be built from. Attempting to create a v8::String from a larger buffer will result in None being returned.

pub fn empty<'s>(scope: &mut HandleScope<'s, ()>) -> Local<'s, String>

pub fn new_from_utf8<'s>( scope: &mut HandleScope<'s, ()>, buffer: &[u8], new_type: NewStringType, ) -> Option<Local<'s, String>>

Allocates a new string from UTF-8 data. Only returns an empty value when length > kMaxLength

pub fn new_from_one_byte<'s>( scope: &mut HandleScope<'s, ()>, buffer: &[u8], new_type: NewStringType, ) -> Option<Local<'s, String>>

Allocates a new string from Latin-1 data. Only returns an empty value when length > kMaxLength.

pub fn new_from_two_byte<'s>( scope: &mut HandleScope<'s, ()>, buffer: &[u16], new_type: NewStringType, ) -> Option<Local<'s, String>>

Allocates a new string from UTF-16 data. Only returns an empty value when length > kMaxLength.

pub fn length(&self) -> usize

Returns the number of characters (UTF-16 code units) in this string.

pub fn utf8_length(&self, scope: &mut Isolate) -> usize

Returns the number of bytes in the UTF-8 encoded representation of this string.

pub fn write( &self, scope: &mut Isolate, buffer: &mut [u16], start: usize, options: WriteOptions, ) -> usize

Writes the contents of the string to an external buffer, as 16-bit (UTF-16) character codes.

pub fn write_one_byte( &self, scope: &mut Isolate, buffer: &mut [u8], start: usize, options: WriteOptions, ) -> usize

Writes the contents of the string to an external buffer, as one-byte (Latin-1) characters.

pub fn write_one_byte_uninit( &self, scope: &mut Isolate, buffer: &mut [MaybeUninit<u8>], start: usize, options: WriteOptions, ) -> usize

Writes the contents of the string to an external MaybeUninit buffer, as one-byte (Latin-1) characters.

pub fn write_utf8( &self, scope: &mut Isolate, buffer: &mut [u8], nchars_ref: Option<&mut usize>, options: WriteOptions, ) -> usize

Writes the contents of the string to an external buffer, as UTF-8.

pub fn write_utf8_uninit( &self, scope: &mut Isolate, buffer: &mut [MaybeUninit<u8>], nchars_ref: Option<&mut usize>, options: WriteOptions, ) -> usize

Writes the contents of the string to an external MaybeUninit buffer, as UTF-8.

pub fn new<'s>( scope: &mut HandleScope<'s, ()>, value: &str, ) -> Option<Local<'s, String>>

pub const fn create_external_onebyte_const( buffer: &'static [u8], ) -> OneByteConst

Compile-time function to create an external string resource. The buffer is checked to contain only ASCII characters.

pub const unsafe fn create_external_onebyte_const_unchecked( buffer: &'static [u8], ) -> OneByteConst

Compile-time function to create an external string resource which skips the ASCII and length checks.

Safety

The passed in buffer must contain only ASCII data. Note that while V8 allows OneByte string resources to contain Latin-1 data, the OneByteConst struct does not allow it.

pub fn new_from_onebyte_const<'s>( scope: &mut HandleScope<'s, ()>, onebyte_const: &'static OneByteConst, ) -> Option<Local<'s, String>>

Creates a v8::String from a &'static OneByteConst which is guaranteed to be ASCII.

Note that OneByteConst guarantees ASCII even though V8 would allow OneByte string resources to contain Latin-1.

pub fn new_external_onebyte_static<'s>( scope: &mut HandleScope<'s, ()>, buffer: &'static [u8], ) -> Option<Local<'s, String>>

Creates a v8::String from a &'static [u8], must be Latin-1 or ASCII, not UTF-8!

pub fn new_external_onebyte<'s>( scope: &mut HandleScope<'s, ()>, buffer: Box<[u8]>, ) -> Option<Local<'s, String>>

Creates a v8::String from owned bytes. The bytes must be Latin-1 or ASCII. V8 will take ownership of the buffer and free it when the string is garbage collected.

pub unsafe fn new_external_onebyte_raw<'s>( scope: &mut HandleScope<'s, ()>, buffer: *mut char, buffer_len: usize, destructor: extern "C" fn(_: *mut char, _: usize), ) -> Option<Local<'s, String>>

Creates a v8::String from owned bytes, length, and a custom destructor. The bytes must be Latin-1 or ASCII. V8 will take ownership of the buffer and free it when the string is garbage collected.

SAFETY: buffer must be owned (valid for the lifetime of the string), and destructor must be a valid function pointer that can free the buffer. The destructor will be called with the buffer and length when the string is garbage collected.

pub fn new_external_twobyte_static<'s>( scope: &mut HandleScope<'s, ()>, buffer: &'static [u16], ) -> Option<Local<'s, String>>

Creates a v8::String from a &'static [u16].

pub fn get_external_string_resource( &self, ) -> Option<NonNull<ExternalStringResource>>

Get the ExternalStringResource for an external string.

Returns None if is_external() doesn’t return true.

pub fn get_external_onebyte_string_resource( &self, ) -> Option<NonNull<ExternalOneByteStringResource>>

Get the ExternalOneByteStringResource for an external one-byte string.

Returns None if is_external_onebyte() doesn’t return true.

pub fn get_external_string_resource_base( &self, ) -> (Option<NonNull<ExternalStringResourceBase>>, Encoding)

Get the ExternalStringResourceBase for an external string. Note this is just the base class, and isn’t very useful on its own. You’ll want to downcast to one of its subclasses, for instance with get_external_onebyte_string_resource.

pub fn is_external(&self) -> bool

True if string is external

pub fn is_external_onebyte(&self) -> bool

True if string is external & one-byte (e.g: created with new_external_onebyte_static)

pub fn is_external_twobyte(&self) -> bool

True if string is external & two-byte (e.g: created with new_external_twobyte_static)

pub fn is_onebyte(&self) -> bool

Will return true if and only if string is known for certain to contain only one-byte data, ie: Latin-1, a.k.a. ISO-8859-1 code points. Doesn’t read the string so can return false negatives, and a return value of false does not mean this string is not one-byte data.

For a method that will not return false negatives at the cost of potentially reading the entire string, use contains_only_onebyte().

pub fn contains_only_onebyte(&self) -> bool

True if the string contains only one-byte data. Will read the entire string in some cases.

pub fn to_rust_string_lossy(&self, scope: &mut Isolate) -> String

Creates a copy of a crate::String in a std::string::String. Convenience function not present in the original V8 API.

pub fn to_rust_cow_lossy<'a, const N: usize>( &self, scope: &mut Isolate, buffer: &'a mut [MaybeUninit<u8>; N], ) -> Cow<'a, str>

Converts a crate::String to either an owned std::string::String, or a borrowed str, depending on whether it fits into the provided buffer.

Methods from Deref<Target = Name>

pub fn get_identity_hash(&self) -> NonZeroI32

Returns the V8 hash value for this value. The current implementation uses a hidden property to store the identity hash.

The return value will never be 0. Also, it is not guaranteed to be unique.

Methods from Deref<Target = Value>

pub fn is_undefined(&self) -> bool

Returns true if this value is the undefined value. See ECMA-262 4.3.10.

pub fn is_null(&self) -> bool

Returns true if this value is the null value. See ECMA-262 4.3.11.

pub fn is_null_or_undefined(&self) -> bool

Returns true if this value is either the null or the undefined value. See ECMA-262 4.3.11. and 4.3.12

pub fn is_true(&self) -> bool

Returns true if this value is true. This is not the same as BooleanValue(). The latter performs a conversion to boolean, i.e. the result of Boolean(value) in JS, whereas this checks value === true.

pub fn is_false(&self) -> bool

Returns true if this value is false. This is not the same as !BooleanValue(). The latter performs a conversion to boolean, i.e. the result of !Boolean(value) in JS, whereas this checks value === false.

pub fn is_name(&self) -> bool

Returns true if this value is a symbol or a string. This is equivalent to typeof value === 'string' || typeof value === 'symbol' in JS.

pub fn is_string(&self) -> bool

Returns true if this value is an instance of the String type. See ECMA-262 8.4.

pub fn is_symbol(&self) -> bool

Returns true if this value is a symbol. This is equivalent to typeof value === 'symbol' in JS.

pub fn is_function(&self) -> bool

Returns true if this value is a function.

pub fn is_array(&self) -> bool

Returns true if this value is an array. Note that it will return false for an Proxy for an array.

pub fn is_object(&self) -> bool

Returns true if this value is an object.

pub fn is_big_int(&self) -> bool

Returns true if this value is a bigint. This is equivalent to typeof value === 'bigint' in JS.

pub fn is_boolean(&self) -> bool

Returns true if this value is boolean. This is equivalent to typeof value === 'boolean' in JS.

pub fn is_number(&self) -> bool

Returns true if this value is a number.

pub fn is_external(&self) -> bool

Returns true if this value is an External object.

pub fn is_int32(&self) -> bool

Returns true if this value is a 32-bit signed integer.

pub fn is_uint32(&self) -> bool

Returns true if this value is a 32-bit unsigned integer.

pub fn is_date(&self) -> bool

Returns true if this value is a Date.

pub fn is_arguments_object(&self) -> bool

Returns true if this value is an Arguments object.

pub fn is_big_int_object(&self) -> bool

Returns true if this value is a BigInt object.

pub fn is_boolean_object(&self) -> bool

Returns true if this value is a Boolean object.

pub fn is_number_object(&self) -> bool

Returns true if this value is a Number object.

pub fn is_string_object(&self) -> bool

Returns true if this value is a String object.

pub fn is_symbol_object(&self) -> bool

Returns true if this value is a Symbol object.

pub fn is_native_error(&self) -> bool

Returns true if this value is a NativeError.

pub fn is_reg_exp(&self) -> bool

Returns true if this value is a RegExp.

pub fn is_async_function(&self) -> bool

Returns true if this value is an async function.

pub fn is_generator_function(&self) -> bool

Returns true if this value is a Generator function.

pub fn is_promise(&self) -> bool

Returns true if this value is a Promise.

pub fn is_map(&self) -> bool

Returns true if this value is a Map.

pub fn is_set(&self) -> bool

Returns true if this value is a Set.

pub fn is_map_iterator(&self) -> bool

Returns true if this value is a Map Iterator.

pub fn is_set_iterator(&self) -> bool

Returns true if this value is a Set Iterator.

pub fn is_generator_object(&self) -> bool

Returns true if this value is a Generator Object.

pub fn is_weak_map(&self) -> bool

Returns true if this value is a WeakMap.

pub fn is_weak_set(&self) -> bool

Returns true if this value is a WeakSet.

pub fn is_array_buffer(&self) -> bool

Returns true if this value is an ArrayBuffer.

pub fn is_array_buffer_view(&self) -> bool

Returns true if this value is an ArrayBufferView.

pub fn is_typed_array(&self) -> bool

Returns true if this value is one of TypedArrays.

pub fn is_uint8_array(&self) -> bool

Returns true if this value is an Uint8Array.

pub fn is_uint8_clamped_array(&self) -> bool

Returns true if this value is an Uint8ClampedArray.

pub fn is_int8_array(&self) -> bool

Returns true if this value is an Int8Array.

pub fn is_uint16_array(&self) -> bool

Returns true if this value is an Uint16Array.

pub fn is_int16_array(&self) -> bool

Returns true if this value is an Int16Array.

pub fn is_uint32_array(&self) -> bool

Returns true if this value is an Uint32Array.

pub fn is_int32_array(&self) -> bool

Returns true if this value is an Int32Array.

pub fn is_float32_array(&self) -> bool

Returns true if this value is a Float32Array.

pub fn is_float64_array(&self) -> bool

Returns true if this value is a Float64Array.

pub fn is_big_int64_array(&self) -> bool

Returns true if this value is a BigInt64Array.

pub fn is_big_uint64_array(&self) -> bool

Returns true if this value is a BigUint64Array.

pub fn is_data_view(&self) -> bool

Returns true if this value is a DataView.

pub fn is_shared_array_buffer(&self) -> bool

Returns true if this value is a SharedArrayBuffer. This is an experimental feature.

pub fn is_proxy(&self) -> bool

Returns true if this value is a JavaScript Proxy.

pub fn is_wasm_memory_object(&self) -> bool

Returns true if this value is a WasmMemoryObject.

pub fn is_wasm_module_object(&self) -> bool

Returns true if this value is a WasmModuleObject.

pub fn is_module_namespace_object(&self) -> bool

Returns true if the value is a Module Namespace Object.

pub fn strict_equals(&self, that: Local<'_, Value>) -> bool

pub fn same_value(&self, that: Local<'_, Value>) -> bool

pub fn same_value_zero(&self, that: Local<'_, Value>) -> bool

Implements the the abstract operation SameValueZero, which is defined in ECMA-262 6th edition § 7.2.10 (http://ecma-international.org/ecma-262/6.0/#sec-samevaluezero).

This operation is used to compare values for the purpose of insertion into a Set, or determining whether Map keys are equivalent. Its semantics are almost the same as strict_equals() and same_value(), with the following important distinctions:

• It considers NaN equal to NaN (unlike strict_equals()).
• It considers -0 equal to 0 (unlike same_value()).

pub fn to_big_int<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, BigInt>>

pub fn to_number<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, Number>>

pub fn to_string<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, String>>

pub fn to_rust_string_lossy(&self, scope: &mut HandleScope<'_>) -> String

Convenience function not present in the original V8 API.

pub fn to_detail_string<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, String>>

pub fn to_object<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, Object>>

pub fn to_integer<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, Integer>>

pub fn to_uint32<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, Uint32>>

pub fn to_int32<'s>( &self, scope: &mut HandleScope<'s>, ) -> Option<Local<'s, Int32>>

pub fn to_boolean<'s>( &self, scope: &mut HandleScope<'s, ()>, ) -> Local<'s, Boolean>

Perform the equivalent of Boolean(value) in JS. This can never fail.

pub fn instance_of( &self, scope: &mut HandleScope<'_>, object: Local<'_, Object>, ) -> Option<bool>

pub fn number_value(&self, scope: &mut HandleScope<'_>) -> Option<f64>

pub fn integer_value(&self, scope: &mut HandleScope<'_>) -> Option<i64>

pub fn uint32_value(&self, scope: &mut HandleScope<'_>) -> Option<u32>

pub fn int32_value(&self, scope: &mut HandleScope<'_>) -> Option<i32>

pub fn boolean_value(&self, scope: &mut HandleScope<'_, ()>) -> bool

pub fn get_hash(&self) -> NonZeroI32

Returns the V8 hash value for this value. The current implementation uses a hidden property to store the identity hash on some object types.

The return value will never be 0. Also, it is not guaranteed to be unique.

pub fn type_of<'s>(&self, scope: &mut HandleScope<'s, ()>) -> Local<'s, String>

pub fn type_repr(&self) -> &'static str

Utility method that returns human readable representation of the underlying value.

Methods from Deref<Target = Data>

pub fn is_big_int(&self) -> bool

Returns true if this data is a BigInt.

pub fn is_boolean(&self) -> bool

Returns true if this data is a Boolean.

pub fn is_context(&self) -> bool

Returns true if this data is a Context.

pub fn is_fixed_array(&self) -> bool

Returns true if this data is a FixedArray.

pub fn is_function_template(&self) -> bool

Returns true if this data is a FunctionTemplate.

pub fn is_module(&self) -> bool

Returns true if this data is a Module.

pub fn is_module_request(&self) -> bool

Returns true if this data is a ModuleRequest.

pub fn is_name(&self) -> bool

Returns true if this data is a Name.

pub fn is_number(&self) -> bool

Returns true if this data is a Number.

pub fn is_object_template(&self) -> bool

Returns true if this data is a ObjectTemplate.

pub fn is_primitive(&self) -> bool

Returns true if this data is a Primitive.

pub fn is_private(&self) -> bool

Returns true if this data is a Private.

pub fn is_string(&self) -> bool

Returns true if this data is a String.

pub fn is_symbol(&self) -> bool

Returns true if this data is a Symbol.

pub fn is_value(&self) -> bool

Returns true if this data is a Value.

Trait Implementations

impl Debug for String

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for String

type Target = Name

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for String

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'s> PartialEq<Name> for String

fn eq(&self, other: &Name) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<Primitive> for String

fn eq(&self, other: &Primitive) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<String> for Name

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<String> for Primitive

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<String> for Value

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq<Value> for String

fn eq(&self, other: &Value) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s> PartialEq for String

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for String