HS_popEStack Function (ROM Call 0x244)

homescr.h, estack.h

HANDLE HS_popEStack (void);

Pops the entire expression stack into memory.

HS_popEStack allocates a block in memory, pops the entire expression stack into the allocated block, and returns a handle which points to it. More precisely, it creates a MULTI_EXPR structure holding the expression stack. If there is not enough memory, it throws an error. See NG_execute for an example of usage. The returned handle is allocated with HeapAllocHigh, and is therefore intended to be temporary. However, it is unlocked.

This function copies everything from bottom_estack to top_estack (including both bottom_estack and top_estack), and resets top_estack to bottom_estack. This means that the size of the allocated block is top_estack - bottom_estack + 3 (because the MULTI_EXPR structure reserves two bytes for the size). By changing bottom_estack temporarily, it is theoretically possible to set the block which is to be popped off manually. However, you need to take care of the requirement that bottom_estack has to point to an ENDSTACK_TAG quantum.

This function is intended to copy an expression into memory so that it can be pushed to the Home Screen using HS_pushFIFONode or one of its wrapper functions.


Uses: HeapAllocHigh, HeapUnlock, bottom_estack, top_estack, memcpy
Used by: HomeExecute