java.lang.Object
- com.tonic.analysis.simulation.core.SimulationState

```
public final class SimulationState
extends Object
```
Immutable snapshot of stack, locals, heap and position at one point during simulation.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`SimulationState`	`atBlock(IRBlock block)`	Move to a new block.
`SimulationState`	`atInstruction(int index)`	Move to a specific instruction index.
`SimulationState`	`clearStack()`	Clear the stack (for exception handlers).
`SimulationState`	`dup()`	Duplicate top stack value (dup).
`SimulationState`	`dup2()`	Duplicate top two values (dup2).
`SimulationState`	`dup2X1()`	Duplicate two with insertion (dup2_x1).
`SimulationState`	`dup2X2()`	Duplicate two with insertion (dup2_x2).
`SimulationState`	`dupX1()`	Duplicate with insertion (dup_x1).
`SimulationState`	`dupX2()`	Duplicate with insertion (dup_x2).
`static SimulationState`	`empty()`	Create an initial empty state.
`SimulationState`	`enterCall()`	Enter a method call (increment call depth).
`boolean`	`equals(Object o)`
`SimulationState`	`exitCall(SimulationState callerState)`	Return from a method call (decrement call depth).
`static SimulationState`	`forMethodEntry(IRBlock entryBlock, LocalState initialLocals)`	Create an initial state for a method entry.
`int`	`getCallDepth()`
`IRBlock`	`getCurrentBlock()`
`IRInstruction`	`getCurrentInstruction()`	Get the instruction at the current position.
`SimHeap`	`getHeap()`
`int`	`getInstructionIndex()`
`SimValue`	`getLocal(int index)`	Get a local variable.
`LocalState`	`getLocals()`
`StackState`	`getStack()`
`int`	`hashCode()`
`boolean`	`hasLocal(int index)`	Check if a local variable is defined.
`boolean`	`isAtBlockEnd()`	Check if at the end of a block.
`boolean`	`isAtBlockStart()`	Check if at the start of a block.
`int`	`maxStackDepth()`	Get the maximum stack depth seen during simulation.
`SimulationState`	`merge(SimulationState other)`	Merge this state with another for control flow convergence.
`SimulationState`	`nextInstruction()`	Advance to the next instruction.
`static SimulationState`	`of(StackState stack, LocalState locals)`	Create state with specific stack and locals.
`SimValue`	`peek()`	Peek at the top value without removing it.
`SimValue`	`peek(int depth)`	Peek at a value at the given depth (0 = top).
`SimValue`	`peekValue()`	Get the top value, accounting for wide types.
`SimValue`	`peekValue(int depth)`	Get value at depth, accounting for wide types.
`SimulationState`	`pop()`	Pop the top value from the stack.
`SimulationState`	`pop(int count)`	Pop multiple values from the stack.
`SimulationState`	`popWide()`	Pop a wide value (2 slots) from the stack.
`SimulationState`	`push(SimValue value)`	Push a value onto the stack.
`SimulationState`	`pushWide(SimValue value)`	Push a wide value (long/double) onto the stack.
`SimulationState`	`setLocal(int index, SimValue value)`	Set a local variable.
`SimulationState`	`setLocalWide(int index, SimValue value)`	Set a wide local variable (long/double).
`StateSnapshot`	`snapshot()`	Create a snapshot of this state for storage.
`int`	`stackDepth()`	Get the current stack depth.
`SimulationState`	`swap()`	Swap top two values.
`String`	`toString()`
`SimulationState`	`withHeap(SimHeap newHeap)`	Create a new state with a different heap.
`SimulationState`	`withLocals(LocalState newLocals)`	Create a new state with different locals.
`SimulationState`	`withStack(StackState newStack)`	Create a new state with a different stack.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - empty
```
public static SimulationState empty()
```
    Create an initial empty state.
    
    Returns:
    
    a state with an empty stack, empty locals and no position
  - forMethodEntry
```
public static SimulationState forMethodEntry(IRBlock entryBlock,
                                             LocalState initialLocals)
```
    Create an initial state for a method entry.
    
    Parameters:
    
    entryBlock - the block execution starts in
    
    initialLocals - the locals holding the incoming parameters
    
    Returns:
    
    a state positioned at the entry block's first instruction with an empty stack
  - of
```
public static SimulationState of(StackState stack,
                                 LocalState locals)
```
    Create state with specific stack and locals.
    
    Parameters:
    
    stack - the operand stack
    
    locals - the local variables
    
    Returns:
    
    a state holding them, with no position
  - push
```
public SimulationState push(SimValue value)
```
    Push a value onto the stack.
    
    Parameters:
    
    value - the value to push
    
    Returns:
    
    a new state with the value on top
  - pushWide
```
public SimulationState pushWide(SimValue value)
```
    Push a wide value (long/double) onto the stack.
    
    Parameters:
    
    value - the value to push
    
    Returns:
    
    a new state with the value occupying two slots
  - pop
```
public SimulationState pop()
```
    Pop the top value from the stack.
    
    Returns:
    
    a new state with the top slot removed
  - pop
```
public SimulationState pop(int count)
```
    Pop multiple values from the stack.
    
    Parameters:
    
    count - how many slots to remove
    
    Returns:
    
    a new state with that many slots removed
  - popWide
```
public SimulationState popWide()
```
    Pop a wide value (2 slots) from the stack.
    
    Returns:
    
    a new state with both slots removed
  - peek
```
public SimValue peek()
```
    Peek at the top value without removing it.
    
    Returns:
    
    the top stack value
  - peek
```
public SimValue peek(int depth)
```
    Peek at a value at the given depth (0 = top).
    
    Parameters:
    
    depth - slots below the top
    
    Returns:
    
    the value in that slot
  - peekValue
```
public SimValue peekValue()
```
    Get the top value, accounting for wide types.
    
    Returns:
    
    the topmost whole value
  - peekValue
```
public SimValue peekValue(int depth)
```
    Get value at depth, accounting for wide types.
    
    Parameters:
    
    depth - slots below the top
    
    Returns:
    
    the whole value at that depth
  - stackDepth
```
public int stackDepth()
```
    Get the current stack depth.
    
    Returns:
    
    the number of occupied stack slots
  - maxStackDepth
```
public int maxStackDepth()
```
    Get the maximum stack depth seen during simulation.
    
    Returns:
    
    the high-water mark of occupied stack slots
  - dup
```
public SimulationState dup()
```
    Duplicate top stack value (dup).
    
    Returns:
    
    a new state with the top slot copied
  - dupX1
```
public SimulationState dupX1()
```
    Duplicate with insertion (dup_x1).
    
    Returns:
    
    a new state with the top slot copied two slots down
  - dupX2
```
public SimulationState dupX2()
```
    Duplicate with insertion (dup_x2).
    
    Returns:
    
    a new state with the top slot copied three slots down
  - dup2
```
public SimulationState dup2()
```
    Duplicate top two values (dup2).
    
    Returns:
    
    a new state with the top two slots copied
  - dup2X1
```
public SimulationState dup2X1()
```
    Duplicate two with insertion (dup2_x1).
    
    Returns:
    
    a new state with the top two slots copied three slots down
  - dup2X2
```
public SimulationState dup2X2()
```
    Duplicate two with insertion (dup2_x2).
    
    Returns:
    
    a new state with the top two slots copied four slots down
  - swap
```
public SimulationState swap()
```
    Swap top two values.
    
    Returns:
    
    a new state with the top two slots exchanged
  - clearStack
```
public SimulationState clearStack()
```
    Clear the stack (for exception handlers).
    
    Returns:
    
    a new state with an empty stack and the locals kept
  - setLocal
```
public SimulationState setLocal(int index,
                                SimValue value)
```
    Set a local variable.
    
    Parameters:
    
    index - the local slot
    
    value - the value to store
    
    Returns:
    
    a new state with that slot bound
  - setLocalWide
```
public SimulationState setLocalWide(int index,
                                    SimValue value)
```
    Set a wide local variable (long/double).
    
    Parameters:
    
    index - the first of the two local slots
    
    value - the value to store
    
    Returns:
    
    a new state with both slots bound
  - getLocal
```
public SimValue getLocal(int index)
```
    Get a local variable.
    
    Parameters:
    
    index - the local slot
    
    Returns:
    
    the value in that slot
  - hasLocal
```
public boolean hasLocal(int index)
```
    Check if a local variable is defined.
    
    Parameters:
    
    index - the local slot
    
    Returns:
    
    true when the slot holds a value
  - atBlock
```
public SimulationState atBlock(IRBlock block)
```
    Move to a new block.
    
    Parameters:
    
    block - the block to enter
    
    Returns:
    
    a new state positioned at that block's first instruction
  - atInstruction
```
public SimulationState atInstruction(int index)
```
    Move to a specific instruction index.
    
    Parameters:
    
    index - the instruction index within the current block
    
    Returns:
    
    a new state positioned there
  - nextInstruction
```
public SimulationState nextInstruction()
```
    Advance to the next instruction.
    
    Returns:
    
    a new state with the instruction index incremented
  - enterCall
```
public SimulationState enterCall()
```
    Enter a method call (increment call depth).
    
    Returns:
    
    a new state with a fresh stack and locals at one deeper call level, sharing the heap
  - exitCall
```
public SimulationState exitCall(SimulationState callerState)
```
    Return from a method call (decrement call depth).
    
    Parameters:
    
    callerState - the state captured before the call was entered
    
    Returns:
    
    a new state restoring the caller's stack, locals and position, keeping this heap
  - getStack
```
public StackState getStack()
```
    Returns:
    
    the operand stack state
  - getLocals
```
public LocalState getLocals()
```
    Returns:
    
    the local variable state
  - getCurrentBlock
```
public IRBlock getCurrentBlock()
```
    Returns:
    
    the block being executed, or null when the state has no position
  - getInstructionIndex
```
public int getInstructionIndex()
```
    Returns:
    
    the instruction index within the current block
  - getCallDepth
```
public int getCallDepth()
```
    Returns:
    
    the call depth (0 = top-level)
  - getHeap
```
public SimHeap getHeap()
```
    Returns:
    
    the simulation heap
  - getCurrentInstruction
```
public IRInstruction getCurrentInstruction()
```
    Get the instruction at the current position.
    
    Returns:
    
    the instruction, or null when there is no block or the index is out of range
  - isAtBlockStart
```
public boolean isAtBlockStart()
```
    Check if at the start of a block.
    
    Returns:
    
    true when the instruction index is 0
  - isAtBlockEnd
```
public boolean isAtBlockEnd()
```
    Check if at the end of a block.
    
    Returns:
    
    true when there is no block, or the index is past its last instruction
  - merge
```
public SimulationState merge(SimulationState other)
```
    Merge this state with another for control flow convergence.
    
    Parameters:
    
    other - the incoming state, may be null
    
    Returns:
    
    the merged state, or this one when other is null; this state's position is kept
  - snapshot
```
public StateSnapshot snapshot()
```
    Create a snapshot of this state for storage.
    
    Returns:
    
    a snapshot wrapping this state
  - withStack
```
public SimulationState withStack(StackState newStack)
```
    Create a new state with a different stack.
    
    Parameters:
    
    newStack - the replacement operand stack
    
    Returns:
    
    a new state with everything else unchanged
  - withLocals
```
public SimulationState withLocals(LocalState newLocals)
```
    Create a new state with different locals.
    
    Parameters:
    
    newLocals - the replacement local variables
    
    Returns:
    
    a new state with everything else unchanged
  - withHeap
```
public SimulationState withHeap(SimHeap newHeap)
```
    Create a new state with a different heap.
    
    Parameters:
    
    newHeap - the replacement heap
    
    Returns:
    
    a new state with everything else unchanged
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class SimulationState

Method Summary

Methods inherited from class java.lang.Object

Method Detail

empty

forMethodEntry

of

push

pushWide

pop

pop

popWide

peek

peek

peekValue

peekValue

stackDepth

maxStackDepth

dup

dupX1

dupX2

dup2

dup2X1

dup2X2

swap

clearStack

setLocal

setLocalWide

getLocal

hasLocal

atBlock

atInstruction

nextInstruction

enterCall

exitCall

getStack

getLocals

getCurrentBlock

getInstructionIndex

getCallDepth

getHeap

getCurrentInstruction

isAtBlockStart

isAtBlockEnd

merge

snapshot

withStack

withLocals

withHeap

equals

hashCode

toString