pub struct JsString(/* private fields */);Expand description
ECMAScript strings are sequences of UTF-16 code units, not UTF-8 scalar values. Compact Latin-1/UTF-16 leaves and bounded ropes mirror QuickJS’s current representation while preserving lone surrogates.
Implementations§
Source§impl JsString
impl JsString
pub fn downgrade(&self) -> WeakJsString
pub fn same_representation(&self, other: &Self) -> bool
pub fn content_hash(&self) -> u32
pub fn checked_length_with_limit( current: usize, additional: usize, limit: usize, ) -> Result<usize, JsStringError>
pub fn checked_length( current: usize, additional: usize, ) -> Result<usize, JsStringError>
Sourcepub fn try_from_utf8(value: &str) -> Result<Self, JsStringError>
pub fn try_from_utf8(value: &str) -> Result<Self, JsStringError>
Construct a dynamically supplied UTF-8 string while enforcing QuickJS’s 30-bit UTF-16 length limit.
§Errors
Returns JsStringError::TooLong when the decoded value exceeds
Self::MAX_LEN. Recoverable allocator failure remains a separate
parity gap.
Sourcepub fn try_from_bytes(value: &[u8]) -> Result<Self, JsStringError>
pub fn try_from_bytes(value: &[u8]) -> Result<Self, JsStringError>
Decode the byte-oriented input accepted by QuickJS JS_NewStringLen.
This is deliberately not Rust’s strict or standard lossy UTF-8 decoder. Three-byte surrogate encodings are preserved as UTF-16 code units, non-BMP scalars become surrogate pairs, and malformed sequences use QuickJS’s release-pinned replacement-and-skip algorithm. Embedded NUL bytes are ordinary U+0000 code units because the input length is explicit.
§Errors
Returns JsStringError::TooLong when the decoded value exceeds
Self::MAX_LEN UTF-16 code units. Recoverable allocation failure for
String storage remains a separate parity gap.
Sourcepub fn from_static(value: &'static str) -> Self
pub fn from_static(value: &'static str) -> Self
Construct one of the engine’s trusted static table/literal strings.
Dynamic host input must use Self::try_from_utf8.
Sourcepub fn try_from_utf16(
units: impl IntoIterator<Item = u16>,
) -> Result<Self, JsStringError>
pub fn try_from_utf16( units: impl IntoIterator<Item = u16>, ) -> Result<Self, JsStringError>
Construct a dynamically supplied UTF-16 string while enforcing QuickJS’s 30-bit code-unit length limit.
The iterator is consumed only after its lower size bound is validated; a dishonest or unbounded upper hint is never used for an enormous eager allocation.
§Errors
Returns JsStringError::TooLong when the value exceeds
Self::MAX_LEN. Recoverable allocator failure remains a separate
parity gap.
pub fn try_from_utf16_with_limit( units: impl IntoIterator<Item = u16>, max_len: usize, ) -> Result<Self, JsStringError>
Sourcepub fn from_owned_latin1(units: Vec<u8>) -> Self
pub fn from_owned_latin1(units: Vec<u8>) -> Self
Adopt a checked narrow result buffer without collecting its contents a
second time. Callers must have enforced Self::MAX_LEN.
Sourcepub fn from_fresh_decimal_u32(value: u32) -> Self
pub fn from_fresh_decimal_u32(value: u32) -> Self
Materialize QuickJS’s JS_AtomToString result for one tagged integer
atom. The returned narrow String deliberately owns a fresh
representation on every call; routing this spelling through an atom or
constant pool would make QuickJS’s representation identity observable.
Sourcepub fn try_from_latin1(units: &[u8]) -> Result<Self, JsStringError>
pub fn try_from_latin1(units: &[u8]) -> Result<Self, JsStringError>
Sourcepub fn try_from_utf16_slice(units: &[u16]) -> Result<Self, JsStringError>
pub fn try_from_utf16_slice(units: &[u16]) -> Result<Self, JsStringError>
A copy of UTF-16 code units, stored narrow when every unit fits in a byte.
§Errors
Returns JsStringError::TooLong past Self::MAX_LEN.
Sourcepub fn from_owned_utf16(units: Vec<u16>) -> Self
pub fn from_owned_utf16(units: Vec<u16>) -> Self
Adopt a checked wide result buffer without collecting its contents a
second time. Callers must have enforced Self::MAX_LEN.
Sourcepub fn from_code_unit(unit: u16) -> Self
pub fn from_code_unit(unit: u16) -> Self
Build the compact one-code-unit form used by String exotic indices and
character methods, equivalent to QuickJS’s js_new_string_char.
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
pub fn utf16_units(&self) -> impl ExactSizeIterator<Item = u16> + '_
Sourcepub fn code_unit_at(&self, index: usize) -> Option<u16>
pub fn code_unit_at(&self, index: usize) -> Option<u16>
Return one UTF-16 code unit without decoding or normalizing surrogate
pairs. This is the equivalent of QuickJS’s string_get fast path.
Sourcepub fn code_point_at(&self, index: usize) -> Option<u32>
pub fn code_point_at(&self, index: usize) -> Option<u32>
Return the code point beginning at one UTF-16 code-unit index. A lead surrogate is combined only with an immediately following trail surrogate; every other code unit is returned unchanged.
Sourcepub fn is_well_formed(&self) -> bool
pub fn is_well_formed(&self) -> bool
Whether every surrogate participates in a valid UTF-16 pair.
Sourcepub fn to_well_formed(&self) -> Self
pub fn to_well_formed(&self) -> Self
Replace each unpaired surrogate with U+FFFD. Well-formed strings retain their existing compact allocation, matching QuickJS’s no-copy path.
pub fn is_wide(&self) -> bool
pub fn is_flat(&self) -> bool
Sourcepub fn for_each_flat_leaf(&self, visitor: impl FnMut(&Self))
pub fn for_each_flat_leaf(&self, visitor: impl FnMut(&Self))
Visit the current flat leaves in logical order without linearizing a
rope. QuickJS’s diagnostic String printer decodes each leaf
independently, so surrogate pairs do not cross a live rope boundary.
A previously linearized rope exposes its replacement flat value as one
leaf, matching QuickJS’s in-place flat + empty transition.
Sourcepub fn linearize(&self) -> Self
pub fn linearize(&self) -> Self
Return a compact flat string, caching the result on a rope. This is the
safe-Rust equivalent of QuickJS js_linearize_string_rope.
Sourcepub fn sub_string(&self, start: usize, end: usize) -> Self
pub fn sub_string(&self, start: usize, end: usize) -> Self
Copy one validated UTF-16 code-unit range with QuickJS
js_sub_string representation rules. Ropes are linearized once, a
full-range request reuses that flat handle, Latin-1 ranges copy their
bytes directly, and UTF-16 ranges scan only the selected units before
choosing a single Latin-1 or UTF-16 allocation.
Sourcepub fn repeat_with_limit(
&self,
count: usize,
max_len: usize,
) -> Result<Self, JsStringError>
pub fn repeat_with_limit( &self, count: usize, max_len: usize, ) -> Result<Self, JsStringError>
Repeat one linearized String into the single flat allocation produced by
QuickJS js_string_repeat. The checked product uses the caller-supplied
limit so native white-box tests can exercise the length failure without
attempting a near-gigabyte allocation.
Sourcepub fn pad_with_limit(
&self,
target_len: usize,
filler: Option<&Self>,
pad_at_end: bool,
max_len: usize,
) -> Result<Self, JsStringError>
pub fn pad_with_limit( &self, target_len: usize, filler: Option<&Self>, pad_at_end: bool, max_len: usize, ) -> Result<Self, JsStringError>
Build the one flat result of pinned QuickJS js_string_pad while
retaining its narrow-first StringBuffer behavior. A wide code unit
triggers one fallible widening reservation at the point it is copied;
unused wide units in a truncated filler therefore do not widen the
result.
Sourcepub fn trim_whitespace(
&self,
trim_start: bool,
trim_end: bool,
) -> Result<Self, JsStringError>
pub fn trim_whitespace( &self, trim_start: bool, trim_end: bool, ) -> Result<Self, JsStringError>
Trim the selected ends with pinned QuickJS js_string_trim and
js_sub_string representation rules. Full-range and empty results do
not enter or consume the partial-substring reservation path; a partial
wide range narrows when every retained UTF-16 code unit fits Latin-1.
Sourcepub fn try_concat(&self, other: &Self) -> Result<Self, JsStringError>
pub fn try_concat(&self, other: &Self) -> Result<Self, JsStringError>
Concatenate with QuickJS’s short-flat/rope thresholds, bounded depth, Fibonacci rebalance and 30-bit length cap.
§Errors
Returns JsStringError::TooLong when the result would exceed
Self::MAX_LEN UTF-16 code units.
Sourcepub fn concat_owned(self, other: &Self) -> Result<Self, JsStringError>
pub fn concat_owned(self, other: &Self) -> Result<Self, JsStringError>
Append to an exclusively owned compatible flat buffer. Shared strings and ropes retain the ordinary concatenation representation rules. The same short-flat thresholds apply even to an exclusively owned buffer.
§Errors
Rejects lengths above MAX_LEN and reports reservation failure.
Sourcepub fn try_to_wtf8_bytes(&self) -> Result<Vec<u8>, TryReserveError>
pub fn try_to_wtf8_bytes(&self) -> Result<Vec<u8>, TryReserveError>
Encode the byte slice exposed by QuickJS JS_ToCStringLen2 when its
cesu8 flag is false.
Valid surrogate pairs become standard four-byte UTF-8. Unpaired surrogates are deliberately retained as three-byte WTF-8 sequences. Embedded U+0000 is returned as an ordinary zero byte; the terminating C NUL owned by QuickJS is not part of its reported length and is therefore not included in this safe Rust byte vector. As in QuickJS, converting a rope caches its flat representation on the shared String identity.
§Errors
Returns TryReserveError if the output buffer cannot be reserved.
Sourcepub fn try_append_wtf8_bytes(
&self,
output: &mut Vec<u8>,
) -> Result<(), TryReserveError>
pub fn try_append_wtf8_bytes( &self, output: &mut Vec<u8>, ) -> Result<(), TryReserveError>
Append the WTF-8 bytes exposed by JS_ToCStringLen2(..., false) to an
existing buffer while preserving the same rope-linearization side
effect as Self::try_to_wtf8_bytes.
Sourcepub fn try_to_cesu8_bytes(&self) -> Result<Vec<u8>, TryReserveError>
pub fn try_to_cesu8_bytes(&self) -> Result<Vec<u8>, TryReserveError>
Encode the byte slice exposed by QuickJS JS_ToCStringLen2 when its
cesu8 flag is true.
Every UTF-16 code unit is encoded independently, so a valid surrogate pair occupies two three-byte CESU-8 sequences. Embedded U+0000 is retained and no trailing C NUL is included in the returned vector. Rope conversion has the same shared flat-cache transition as the WTF-8 path.
§Errors
Returns TryReserveError if the output buffer cannot be reserved.
pub fn wtf8_bytes(&self) -> impl Iterator<Item = u8>
pub fn push_c_string_to(&self, output: &mut NativeErrorMessage)
Sourcepub fn push_atom_get_str_to(&self, output: &mut NativeErrorMessage)
pub fn push_atom_get_str_to(&self, output: &mut NativeErrorMessage)
Reproduce JS_AtomGetStr(..., char buf[64], 64) as consumed by a C
%s native-error argument. Narrow all-ASCII atoms bypass the scratch
buffer; every other text atom is encoded one UTF-16 code unit at a time
and stops before starting a unit once 58 bytes have already been written.
Sourcepub fn to_utf8_lossy(&self) -> String
pub fn to_utf8_lossy(&self) -> String
Lossy conversion is suitable for terminal diagnostics. It must not be used for language-level string comparison or indexing.