Struct WasmDecoder 

pub struct WasmDecoder<'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<'a> WasmDecoder<'a>

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

Initialize a new WasmDecoder from a WASM byte slice

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

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, DecodingError>

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], DecodingError>

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] (WasmDecoder::pc).

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

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, E>( &mut self, f: impl FnOnce(&mut WasmDecoder<'_>) -> Result<T, E>, ) -> Result<(T, usize), E>

Call a closure that may mutate the WasmDecoder

Returns a tuple of the closure’s return value and the number of bytes that the WasmDecoder 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<(), DecodingError>

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] (WasmDecoder::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 WasmDecoder<'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.

impl<'wasm> WasmDecoder<'wasm>

pub fn decode_u8(&mut self) -> Result<u8, DecodingError>

Tries to read one byte and fails if the end of file is reached.

pub fn decode_var_u32(&mut self) -> Result<u32, DecodingError>

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

pub fn decode_f64(&mut self) -> Result<u64, DecodingError>

pub fn decode_var_i32(&mut self) -> Result<i32, DecodingError>

pub fn decode_var_i33_as_u32(&mut self) -> Result<u32, DecodingError>

pub fn decode_f32(&mut self) -> Result<u32, DecodingError>

pub fn decode_var_i64(&mut self) -> Result<i64, DecodingError>

pub fn decode_name(&mut self) -> Result<&'wasm str, DecodingError>

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

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

where T: 'wasm, F: FnMut(&mut WasmDecoder<'wasm>, u32) -> Result<T, E>, E: From<DecodingError>,

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

where T: 'wasm, F: FnMut(&mut WasmDecoder<'wasm>) -> Result<T, E>, E: From<DecodingError>,

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

Trait Implementations

impl<'a> Clone for WasmDecoder<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

type Output = [u8]

The returned type after indexing.

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

Performs the indexing (container[index]) operation.