Struct StackOpsHandler

pub struct StackOpsHandler;

Handles stack operations for the VM

Implementations

impl StackOpsHandler

pub fn push<S>(stack: &mut S, value: Value) -> Result<(), ExecutionError>

where S: StackOperations,

Pushes a value onto the stack

Adds a value to the top of the stack.

Arguments

• stack - The stack to operate on
• value - The value to push onto the stack

Returns

• Ok(()) on success
• Err(ExecutionError) on failure

Examples

let mut stack = MyStack::new();
StackOpsHandler::push(&mut stack, Value::Number(42.0))?;
assert_eq!(stack.pop(), Some(Value::Number(42.0)));

pub fn pop<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Pops a value from the top of the stack

Removes and returns the top value from the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if stack is empty

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
StackOpsHandler::pop(&mut stack)?;
assert!(stack.is_empty());

pub fn dup<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Duplicates the top value on the stack

Pops the top value and pushes it twice, effectively duplicating it.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if stack is empty

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
StackOpsHandler::dup(&mut stack)?;
// Stack now contains: [42.0, 42.0]

pub fn dup2<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Duplicates the top two values on the stack

Pops the top two values and pushes them twice, effectively duplicating them.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if insufficient operands

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
stack.push(Value::Number(100.0));
StackOpsHandler::dup2(&mut stack)?;
// Stack now contains: [42.0, 100.0, 42.0, 100.0]

pub fn swap<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Swaps the top two values on the stack

Exchanges the positions of the top two values on the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if insufficient operands

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
stack.push(Value::Number(100.0));
StackOpsHandler::swap(&mut stack)?;
// Stack now contains: [100.0, 42.0]

pub fn rot<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Rotates the top three values on the stack

Moves the third value to the top, shifting the others down.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if insufficient operands

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(1.0));
stack.push(Value::Number(2.0));
stack.push(Value::Number(3.0));
StackOpsHandler::rot(&mut stack)?;
// Stack now contains: [2.0, 3.0, 1.0]

pub fn over<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Copies the second value to the top of the stack

Pushes a copy of the second value without removing it.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if insufficient operands

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
stack.push(Value::Number(100.0));
StackOpsHandler::over(&mut stack)?;
// Stack now contains: [42.0, 100.0, 42.0]

pub fn drop<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Removes the top value from the stack

Pops and discards the top value from the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if stack is empty

pub fn drop2<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Removes the top two values from the stack

Pops and discards the top two values from the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if insufficient operands

pub fn clear<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Clears all values from the stack

Removes all values from the stack, leaving it empty.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success

pub fn size<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Gets the current size of the stack

Pushes the number of values currently on the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
stack.push(Value::Number(100.0));
StackOpsHandler::size(&mut stack)?;
assert_eq!(stack.pop(), Some(Value::Number(2.0)));

pub fn is_empty<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Checks if the stack is empty

Pushes a boolean indicating whether the stack is empty.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success

Examples

let mut stack = MyStack::new();
StackOpsHandler::is_empty(&mut stack)?;
assert_eq!(stack.pop(), Some(Value::Boolean(true)));

pub fn peek<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Peeks at the top value without removing it

Pushes a copy of the top value without modifying the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if stack is empty

Examples

let mut stack = MyStack::new();
stack.push(Value::Number(42.0));
StackOpsHandler::peek(&mut stack)?;
// Stack now contains: [42.0, 42.0]

pub fn depth<S>(stack: &mut S) -> Result<(), ExecutionError>

where S: StackOperations,

Gets the depth of the stack

Pushes the current depth (number of values) on the stack.

Arguments

• stack - The stack to operate on

Returns

• Ok(()) on success

pub fn reserve<S>(stack: &mut S, capacity: usize) -> Result<(), ExecutionError>

where S: StackOperations,

Reserves space on the stack

Ensures the stack has at least the specified capacity.

Arguments

• stack - The stack to operate on
• capacity - The minimum capacity to reserve

Returns

• Ok(()) on success

pub fn truncate<S>(stack: &mut S, size: usize) -> Result<(), ExecutionError>

where S: StackOperations,

Truncates the stack to a specific size

Removes values from the top of the stack until it reaches the specified size.

Arguments

• stack - The stack to operate on
• size - The target size for the stack

Returns

• Ok(()) on success
• Err(ExecutionError::StackUnderflow) if target size is larger than current size