Stack manipulation

Macros
#define	croc_dupTop(t)   (croc_dup((t), -1))
#define	croc_swapTop(t)   (croc_swap((t), -2, -1))
#define	croc_swapTopWith(t, n)   (croc_swap((t), (n), -1))
#define	croc_popTop(t)   (croc_pop((t), 1))
#define	croc_copyTopTo(t, idx)   (croc_copy((t), -1, (idx)))
#define	croc_copyToTop(t, idx)   (croc_copy((t), (idx), -1))

Functions
uword_t	croc_getStackSize (CrocThread *t)
void	croc_setStackSize (CrocThread *t, uword_t newSize)
word_t	croc_absIndex (CrocThread *t, word_t idx)
int	croc_isValidIndex (CrocThread *t, word_t idx)
word_t	croc_dup (CrocThread *t, word_t slot)
void	croc_swap (CrocThread *t, word_t first, word_t second)
void	croc_copy (CrocThread *t, word_t src, word_t dest)
void	croc_replace (CrocThread *t, word_t dest)
void	croc_insert (CrocThread *t, word_t slot)
void	croc_insertAndPop (CrocThread *t, word_t slot)
void	croc_remove (CrocThread *t, word_t slot)
void	croc_moveToTop (CrocThread *t, word_t slot)
void	croc_rotate (CrocThread *t, uword_t numSlots, uword_t dist)
void	croc_rotateAll (CrocThread *t, uword_t dist)
void	croc_pop (CrocThread *t, uword_t n)
void	croc_transferVals (CrocThread *src, CrocThread *dest, uword_t num)

Detailed Description

Moving around stack slots.

Macro Definition Documentation

#define croc_dupTop

(

t

)

(croc_dup((t), -1))

Pushes a copy of the top stack slot.

#define croc_swapTop

(

t

)

(croc_swap((t), -2, -1))

Swaps the top two stack slots.

#define croc_swapTopWith	(		t,
			n
	)		(croc_swap((t), (n), -1))

Swaps the top stack slot with slot n.

#define croc_popTop

(

t

)

(croc_pop((t), 1))

Pops the top stack slot.

#define croc_copyTopTo	(		t,
			idx
	)		(croc_copy((t), -1, (idx)))

Copies the top stack slot into slot idx.

#define croc_copyToTop	(		t,
			idx
	)		(croc_copy((t), (idx), -1))

Copies slot idx into the top stack slot.

Function Documentation

uword_t croc_getStackSize

(

CrocThread *

t

)

Gets the size of the stack.

This is how many slots there are from the bottom of the current function's stack frame to the top of the stack. Valid stack indices range from 0 (the 'this' parameter) to the stack size minus one. Valid negative indices range from -1 to -stack size.

void croc_setStackSize	(	CrocThread *	t,
		uword_t	newSize
	)

Sets the size of the current function's stack.

The size must always be at least 1 (you can't get rid of the 'this' parameter). If you expand the stack, new slots will be filled with null; if you shrink it, values at the top will be removed.

word_t croc_absIndex	(	CrocThread *	t,
		word_t	idx
	)

Converts a given stack index to an absolute index.

For positive indices, this returns the index unchanged. For negative indices, this returns the equivalent positive index.

This is useful when you write your own functions which take stack indices as parameters and then do stack manipulation. In these cases, if a negative stack index is passed to your function, pushing and popping values would change the meaning of the index, so it's best to turn it into an absolute index upon entry to the function.

int croc_isValidIndex	(	CrocThread *	t,
		word_t	idx
	)

Returns

a nonzero value if the given index is valid (either positive or negative), and 0 if not.

word_t croc_dup	(	CrocThread *	t,
		word_t	slot
	)

Pushes a copy of the value at slot on top of the stack.

void croc_swap	(	CrocThread *	t,
		word_t	first,
		word_t	second
	)

Swaps the values held in stack slots first and second.

void croc_copy	(	CrocThread *	t,
		word_t	src,
		word_t	dest
	)

Copies the value from the stack slot src into the stack slot dest, overwriting whatever value was in it.

dest cannot be 0.

void croc_replace	(	CrocThread *	t,
		word_t	dest
	)

Pops the top value off the stack, and replaces the stack slot dest with the value that was popped.

dest cannot be 0.

void croc_insert	(	CrocThread *	t,
		word_t	slot
	)

Pops the top value off the stack, and inserts it before the value at slot, sliding the values from slot up.

slot cannot be 0.

void croc_insertAndPop	(	CrocThread *	t,
		word_t	slot
	)

Places the value on top of the stack into slot and pops all the values above that slot, making slot the new top of the stack.

This is like doing an insert followed by a pop, but does so more efficiently. slot cannot be 0.

void croc_remove	(	CrocThread *	t,
		word_t	slot
	)

Removes the stack slot slot, sliding the values above it down.

slot cannot be 0.

void croc_moveToTop	(	CrocThread *	t,
		word_t	slot
	)

Removes the stack slot slot, slides the values above it down, and pushes the removed slot on top of the stack.

slot cannot be 0.

void croc_rotate	(	CrocThread *	t,
		uword_t	numSlots,
		uword_t	dist
	)

Sort of a generic version of croc_insert, this "rotates" the top numSlot stack slots by dist.

To illustrate, suppose the stack looks like:

1 2 3 4 5 6

If you perform croc_rotate(t, 5, 3), the top 5 slots will be rotated by 3. This means the top 3 slots will exchange positions with the other two slots, giving:

1 4 5 6 2 3

If the dist parameter is 1, it works exactly like croc_insert, and if it's numSlots - 1, it works exactly like croc_moveToTop.

You cannot rotate slot 0.

Rotating 0 or 1 slots is valid and does nothing.

void croc_rotateAll	(	CrocThread *	t,
		uword_t	dist
	)

Rotates all stack slots except slot 0.

void croc_pop	(	CrocThread *	t,
		uword_t	n
	)

Pops 1 or more slots off the top of the stack, moving the top of the stack down.

You cannot pop 0 slots, and you cannot pop slot 0.

void croc_transferVals	(	CrocThread *	src,
		CrocThread *	dest,
		uword_t	num
	)

Moves values from one thread to another.

Both threads must belong to the same VM or an error will be thrown in the source thread. The top num values are popped off the source thread's stack and pushed onto the destination thread's stack in the same order as they originally appeared.