Struct wasm::core::reader::WasmReader

pub struct WasmReader<'a> {
    pub full_wasm_binary: &'a [u8],
    pub pc: usize,
}

A struct for managing and reading WASM bytecode

Its purpose is to abstract parsing basic WASM values from the bytecode.

Fields

full_wasm_binary: &'a [u8]

Entire WASM binary as slice

pc: usize

Current program counter, i. e. index of the next byte to be consumed from the WASM binary

Correctness Note

The pc points to the next byte to be consumed from the WASM binary. Therefore, after consuming last byte, this cursor will advance past the last byte; for a WASM binary that is 100 bytes long (valid indexes start with 0 and end with 99), the pc therefore can become 100. However, it can not advance further.

The table below illustrates this with an example for a WASM binary that is 5 bytes long:

Index	0	1	2	3	4	5	6
full_wasm_binary[index]	0xaa	0xbb	0xcc	0xee	0xff	-	-
Valid pc position?	✅	✅	✅	✅	✅	✅	❌

Implementations

impl WasmReader<'_>

pub fn read_u8(&mut self) -> Result<u8>

Note: If Err, the WasmReader object is no longer guaranteed to be in a valid state

pub fn read_var_u32(&mut self) -> Result<u32>

Parses a variable-length u32 as specified by LEB128. Note: If Err, the WasmReader object is no longer guaranteed to be in a valid state

pub fn read_var_f64(&mut self) -> Result<u64>

pub fn read_var_i32(&mut self) -> Result<i32>

pub fn read_var_f32(&mut self) -> Result<u32>

pub fn read_var_i64(&mut self) -> Result<i64>

pub fn read_name(&mut self) -> Result<&str>

Note: If Err, the WasmReader object is no longer guaranteed to be in a valid state

pub fn read_vec_enumerated<T, F>(&mut self, read_element: F) -> Result<Vec<T>>

where F: FnMut(&mut WasmReader<'_>, usize) -> Result<T>,

pub fn read_vec<T, F>(&mut self, read_element: F) -> Result<Vec<T>>

where F: FnMut(&mut WasmReader<'_>) -> Result<T>,

Note: If Err, the WasmReader object is no longer guaranteed to be in a valid state

impl<'a> WasmReader<'a>

pub const fn new(wasm: &'a [u8]) -> Self

Initialize a new WasmReader from a WASM byte slice

pub fn move_start_to(&mut self, span: Span) -> Result<()>

Advance the cursor to the first byte of the provided Span and validates that entire Span fits the WASM binary

Note

This allows setting the pc to one byte past the end of full_wasm_binary, if the Span’s length is 0. For further information, refer to the field documentation of pc.

pub fn remaining_bytes(&self) -> &[u8]

Byte slice to the remainder of the WASM binary, beginning from the current pc

pub fn make_span(&self, len: usize) -> Result<Span>

Create a Span starting from pc for the next len bytes

Verifies the span to fit the WASM binary, i.e. using this span to index the WASM binary will not yield an error.

pub fn strip_bytes<const N: usize>(&mut self) -> Result<[u8; N]>

Take N bytes starting from pc, then advance the pc by N

This yields back an array of the correct length

Note

This allows setting the pc to one byte past the end of full_wasm_binary, if N equals the remaining bytes slice’s length. For further information, refer to the [field documentation of pc] (WasmReader::pc).

pub fn peek_u8(&self) -> Result<u8>

Read the current byte without advancing the pc

May yield an error if the pc advanced past the end of the WASM binary slice

pub fn measure_num_read_bytes<T>( &mut self, f: impl FnOnce(&mut WasmReader<'_>) -> Result<T> ) -> Result<(T, usize)>

Call a closure that may mutate the WasmReader

Returns a tuple of the closure’s return value and the number of bytes that the WasmReader was advanced by.

Panics

May panic if the closure moved the pc backwards, e.g. when move_start_to is called.

pub fn skip(&mut self, num_bytes: usize) -> Result<()>

Skip num_bytes, advancing the pc accordingly

Note

This can move the pc past the last byte of the WASM binary, so that reading more than 0 further bytes would panick. However, it can not move the pc any further than that, instead an error is returned. For further information, refer to the [field documentation of pc] (WasmReader::pc).

pub fn into_inner(self) -> &'a [u8]

Consumes Self, yielding back the internal reference to the WASM binary

pub fn handle_transaction<T, E>( &mut self, f: impl FnOnce(&mut WasmReader<'a>) -> Result<T, E> ) -> Result<T, E>

A wrapper function for reads with transaction-like behavior.

The provided closure will be called with &mut self and its result will be returned. However if the closure returns Err(_), self will be reset as if the closure was never called.

Trait Implementations

impl<'a> Clone for WasmReader<'a>

fn clone(&self) -> WasmReader<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Index<Span> for WasmReader<'a>

type Output = [u8]

The returned type after indexing.

fn index(&self, index: Span) -> &'a Self::Output

Performs the indexing (container[index]) operation.