Struct wasm_encoder::Function

source ·

pub struct Function { /* private fields */ }

Expand description

An encoder for a function body within the code section.

§Example

use wasm_encoder::{CodeSection, Function, Instruction};

// Define the function body for:
//
//     (func (param i32 i32) (result i32)
//       local.get 0
//       local.get 1
//       i32.add)
let locals = vec![];
let mut func = Function::new(locals);
func.instruction(&Instruction::LocalGet(0));
func.instruction(&Instruction::LocalGet(1));
func.instruction(&Instruction::I32Add);

// Add our function to the code section.
let mut code = CodeSection::new();
code.function(&func);

Implementations§

source §

impl Function

source

pub fn new<L>(locals: L) -> Self
where L: IntoIterator<Item = (u32, ValType)>, L::IntoIter: ExactSizeIterator,

Create a new function body with the given locals.

The argument is an iterator over (N, Ty), which defines that the next N locals will be of type Ty.

For example, a function with locals 0 and 1 of type I32 and local 2 of type F32 would be created as:

let f = Function::new([(2, ValType::I32), (1, ValType::F32)]);

For more information about the code section (and function definition) in the WASM binary format see the WebAssembly spec

source

pub fn new_with_locals_types<L>(locals: L) -> Self
where L: IntoIterator<Item = ValType>,

Create a function from a list of locals’ types.

Unlike Function::new, this constructor simply takes a list of types which are in order associated with locals.

For example:

let f = Function::new([(2, ValType::I32), (1, ValType::F32)]);
let g = Function::new_with_locals_types([
   ValType::I32, ValType::I32, ValType::F32
]);

assert_eq!(f, g)

source

pub fn instruction(&mut self, instruction: &Instruction<'_>) -> &mut Self

Write an instruction into this function body.

source

pub fn raw(&mut self, bytes: B) -> &mut Self
where B: IntoIterator<Item = u8>,

Add raw bytes to this function’s body.

source

pub fn byte_len(&self) -> usize

The number of bytes already added to this function.

This number doesn’t include the variable-width size field that encode will write before the added bytes, since the size of that field isn’t known until all the instructions are added to this function.

source

pub fn into_raw_body(self) -> Vec<u8>

Unwraps and returns the raw byte encoding of this function.

This encoding doesn’t include the variable-width size field that encode will write before the added bytes. As such, its length will match the return value of [byte_len].

§Use Case

This raw byte form is suitable for later using with CodeSection::raw. Note that it differs from what results from Function::encode precisely due to the lack of the length prefix; CodeSection::raw will use this. Using Function::encode instead produces bytes that cannot be fed into other wasm-encoder types without stripping off the length prefix, which is awkward and error-prone.

This method combined with CodeSection::raw may be useful together if one wants to save the result of function encoding and use it later: for example, caching the result of some code generation process.

For example:

let mut f = Function::new([]);
f.instruction(&Instruction::End);
let bytes = f.into_raw_body();
// (save `bytes` somewhere for later use)
let mut code = CodeSection::new();
code.raw(&bytes[..]);

assert_eq!(2, bytes.len());  // Locals count, then `end`
assert_eq!(3, code.byte_len()); // Function length byte, function body