pub struct WasmStr { /* private fields */ }runtime and component-model only.Expand description
Representation of a string located in linear memory in a WebAssembly instance.
This type can be used in place of String and str for string-taking APIs
in some situations. The purpose of this type is to represent a range of
validated bytes within a component but does not actually copy the bytes. The
primary method, WasmStr::to_str, attempts to return a reference to the
string directly located in the component’s memory, avoiding a copy into the
host if possible.
The downside of this type, however, is that accessing a string requires a
Store pointer (via StoreContext). Bindings generated
by bindgen!, for example, do not have access
to StoreContext and thus can’t use this type.
This is intended for more advanced use cases such as defining functions
directly in a Linker. It’s expected that in
the future bindgen! will also have a way to
use this type.
This type is used with TypedFunc, for example, when WebAssembly returns
a string. This type cannot be used to give a string to WebAssembly, instead
&str should be used for that (since it’s coming from the host).
Note that this type represents an in-bounds string in linear memory, but it
does not represent a valid string (e.g. valid utf-8). Validation happens
when WasmStr::to_str is called.
Also note that this type does not implement Lower, it only implements
Lift.
Implementations§
source§impl WasmStr
impl WasmStr
sourcepub fn to_str<'a, T: 'a>(
&self,
store: impl Into<StoreContext<'a, T>>
) -> Result<Cow<'a, str>>
pub fn to_str<'a, T: 'a>( &self, store: impl Into<StoreContext<'a, T>> ) -> Result<Cow<'a, str>>
Returns the underlying string that this cursor points to.
Note that this will internally decode the string from the wasm’s encoding to utf-8 and additionally perform validation.
The store provided must be the store where this string lives to
access the correct memory.
§Errors
Returns an error if the string wasn’t encoded correctly (e.g. invalid utf-8).
§Panics
Panics if this string is not owned by store.