Struct WasmStr

pub struct WasmStr { /* private fields */ }

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

impl WasmStr

pub fn to_str<'a, T>( &self, store: impl Into<StoreContext<'a, T>>, ) -> Result<Cow<'a, str>, Error>

where T: 'a,

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.

Trait Implementations

impl ComponentType for WasmStr

impl Lift for WasmStr