Package: org.codehaus.groovy.classgen.asm

## [Java] Class OperandStack

- org.codehaus.groovy.classgen.asm.OperandStack

-     public class OperandStack
      extends Object

  Tracks the JVM operand stack during bytecode generation, maintaining a parallel list of ClassNode type descriptors for each slot. Used to emit correct pop/cast/box instructions and to verify stack discipline.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `OperandStack(WriterController controller)` Creates an operand stack tracker backed by the given controller.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public ClassNode` | `box()` Boxes the top operand if it is a primitive type, emitting the appropriate wrapper-creation bytecode, and returns the resulting (possibly wrapped) type.
    `` | `public void` | `castToBool(int mark, boolean emptyDefault)` ensure last marked parameter on the stack is a primitive boolean if mark==stack size, we assume an empty expression or statement.
    `` | `public void` | `doAsType(ClassNode targetType)` Performs an `as`-coercion of the top operand to `targetType`.
    `` | `public void` | `doGroovyCast(ClassNode targetType)` do Groovy cast for top level element
    `` | `public void` | `doGroovyCast(Variable v)` Performs a Groovy cast of the top operand to the declared origin type of `v`.
    `` | `public void` | `dup()` duplicate top element
    `` | `public int` | `getStackLength()` Returns the number of tracked entries on the operand stack.
    `` | `public ClassNode` | `getTopOperand()` Returns the type of the top element on the tracked operand stack without removing it.
    `` | `public org.objectweb.asm.Label` | `jump(int ifIns)` Emits a conditional jump instruction and returns the newly created target label.
    `` | `public void` | `jump(int ifIns, org.objectweb.asm.Label label)` Emits a conditional jump to the given label.
    `` | `public void` | `load(ClassNode type, int idx)` Emits a load instruction for the given type from the specified local variable slot and pushes the type onto the tracked stack.
    `` | `public void` | `loadOrStoreVariable(BytecodeVariable variable, boolean useReferenceDirectly)` Either loads or stores a local variable depending on the current LHS flag.
    `` | `public void` | `pop()` remove operand stack top element using bytecode pop
    `` | `public void` | `popDownTo(int elements)` Pops all stack entries above `elements`, emitting the appropriate `POP` or `POP2` instruction for each popped value.
    `` | `public void` | `push(ClassNode type)` push operand on stack
    `` | `public void` | `pushBool(boolean value)` Pushes an integer literal (`0` or `1`) representing a boolean value and tracks it as `boolean` on the operand stack.
    `` | `public void` | `pushConstant(ConstantExpression expression)` load the constant on the operand stack.
    `` | `public void` | `pushDynamicName(Expression name)` Pushes the name expression as a `String` onto the operand stack.
    `` | `public void` | `remove(int amount)` Remove amount elements from the operand stack, without using pop.
    `` | `public void` | `replace(ClassNode type)` replace top level element with new element of given type
    `` | `public void` | `replace(ClassNode type, int n)` replace n top level elements with new element of given type
    `` | `public void` | `storeVar(BytecodeVariable variable)` Stores the top operand stack value into `variable`, casting to the variable's declared type.
    `` | `public void` | `swap()` swap two top level operands
      > `` | `public String` | `toString()` Returns a string representation of the object. API Note: In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The string output is not necessarily stable over time or across JVM invocations. Implementation Requirements: The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:
      >     getClass().getName() + '@' + Integer.toHexString(hashCode())
    Returns: a string representation of the object.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public OperandStack(WriterController controller)

      Creates an operand stack tracker backed by the given controller.

      Parameters:
        `controller` - the writer controller for the current compilation

  - ### Method Detail

    - #### public ClassNode box()

      Boxes the top operand if it is a primitive type, emitting the appropriate wrapper-creation bytecode, and returns the resulting (possibly wrapped) type.

      Returns:
        the type of the top operand after boxing

    - #### public void castToBool(int mark, boolean emptyDefault)

      ensure last marked parameter on the stack is a primitive boolean if mark==stack size, we assume an empty expression or statement. was used and we will use the value given in emptyDefault as boolean if mark==stack.size()-1 the top element will be cast to boolean using Groovy truth. In other cases we throw a GroovyBugError

    - #### public void doAsType(ClassNode targetType)

      Performs an `as`-coercion of the top operand to `targetType`.

      Parameters:
        `targetType` - the target type

    - #### public void doGroovyCast(ClassNode targetType)

      do Groovy cast for top level element

    - #### public void doGroovyCast(Variable v)

      Performs a Groovy cast of the top operand to the declared origin type of `v`.

      Parameters:
        `v` - the variable whose origin type is the cast target

    - #### public void dup()

      duplicate top element

    - #### public int getStackLength()

      Returns the number of tracked entries on the operand stack.

    - #### public ClassNode getTopOperand()

      Returns the type of the top element on the tracked operand stack without removing it.

    - #### public org.objectweb.asm.Label jump(int ifIns)

      Emits a conditional jump instruction and returns the newly created target label. The boolean operand is removed from the tracked stack.

      Parameters:
        `ifIns` - the branch opcode (e.g. `IFEQ`, `IFNE`)
      Returns:
        the label that the jump will branch to

    - #### public void jump(int ifIns, org.objectweb.asm.Label label)

      Emits a conditional jump to the given label. The boolean operand is removed from the tracked stack.

      Parameters:
        `ifIns` - the branch opcode (e.g. `IFEQ`, `IFNE`)
        `label` - the branch target

    - #### public void load(ClassNode type, int idx)

      Emits a load instruction for the given type from the specified local variable slot and pushes the type onto the tracked stack.

      Parameters:
        `type` - the type of the value to load
        `idx` - the local variable slot index

    - #### public void loadOrStoreVariable(BytecodeVariable variable, boolean useReferenceDirectly)

      Either loads or stores a local variable depending on the current LHS flag. If in LHS context, stores the top of the operand stack into `variable`; otherwise loads the variable's value onto the stack.

      Parameters:
        `variable` - the bytecode variable to load or store
        `useReferenceDirectly` - if `true`, loads the Reference wrapper directly rather than unboxing it

    - #### public void pop()

      remove operand stack top element using bytecode pop

    - #### public void popDownTo(int elements)

      Pops all stack entries above `elements`, emitting the appropriate `POP` or `POP2` instruction for each popped value.

      Parameters:
        `elements` - the target stack depth to reduce to

    - #### public void push(ClassNode type)

      push operand on stack

    - #### public void pushBool(boolean value)

      Pushes an integer literal (`0` or `1`) representing a boolean value and tracks it as `boolean` on the operand stack.

      Parameters:
        `value` - the boolean value to push

    - #### public void pushConstant(ConstantExpression expression)

      load the constant on the operand stack.

    - #### public void pushDynamicName(Expression name)

      Pushes the name expression as a `String` onto the operand stack. Constant string expressions are pushed as LDC literals; other expressions are cast to `String` via the Groovy runtime.

      Parameters:
        `name` - the expression representing the method or property name

    - #### public void remove(int amount)

      Remove amount elements from the operand stack, without using pop. For example after a method invocation

    - #### public void replace(ClassNode type)

      replace top level element with new element of given type

    - #### public void replace(ClassNode type, int n)

      replace n top level elements with new element of given type

    - #### public void storeVar(BytecodeVariable variable)

      Stores the top operand stack value into `variable`, casting to the variable's declared type. Handles both plain variables and Reference-wrapped closure-shared variables.

      Parameters:
        `variable` - the bytecode variable slot to store into

    - #### public void swap()

      swap two top level operands

    - #### public String toString()

      Returns a string representation of the object.

      API Note:
        In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The string output is not necessarily stable over time or across JVM invocations.
      Implementation Requirements:
        The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

        >     getClass().getName() + '@' + Integer.toHexString(hashCode())

      Returns:
        a string representation of the object.