Functions for manipulating the Teascript value stack from C: pushing, popping, inserting, removing and rearranging values, and making sure there is room for more. Together they form the basis for receiving arguments and returning results when interfacing with Teascript code.
Stack indices are zero-based: 0 is the first value. A negative index counts back from the top, so -1 is the top value. Pseudo-indices (such as the registry and upvalues) are special negative values that do not refer to real stack slots.
TEA_MIN_STACK
Signature
#define TEA_MIN_STACK 20Description
tea_check_stack or tea_test_stack.Example
static void many(tea_State* T)
{
/* needs more than TEA_MIN_STACK slots: reserve them */
tea_check_stack(T, 100, "too many values");
for(int i = 0; i < 100; i++)
tea_push_integer(T, i);
}
See also
TEA_REGISTRY_INDEX
Signature
#define TEA_REGISTRY_INDEX (-10000)Description
See also
TEA_UPVALUES_INDEX
Signature
#define TEA_UPVALUES_INDEX (-11000)Description
tea_upvalue_index rather than this value directly.See also
tea_upvalue_index
Signature
#define tea_upvalue_index(i) (TEA_UPVALUES_INDEX - (i))Description
i of the running C closure. The upvalues are the values that were popped when the closure was created with tea_push_cclosure.Parameters
i- Upvalue number
Example
static void counter(tea_State* T)
{
/* read the first upvalue, bump it and store it back */
tea_push_value(T, tea_upvalue_index(1));
tea_Integer n = tea_get_integer(T, -1) + 1;
tea_pop(T, 1);
tea_push_integer(T, n);
tea_replace(T, tea_upvalue_index(1));
}
See also
tea_absindex
Signature
int tea_absindex(tea_State* T, int index);Description
index into an equivalent absolute index, one that does not depend on the current top of the stack. An index that is already absolute, or a pseudo-index, is returned unchanged.Parameters
T- Teascript state
index- Stack index to convert
Returns
The absolute index corresponding to index.
Example
tea_push_integer(T, 123);
tea_push_integer(T, 456);
tea_push_integer(T, 789); /* [123, 456, 789] */
int abs = tea_absindex(T, -2); /* abs = 1 */
tea_push_integer(T, 101); /* -2 would now mean 789, abs still means 456 */
tea_push_value(T, abs); /* [123, 456, 789, 101, 456] */
See also
tea_get_top
Signature
int tea_get_top(tea_State* T);Description
n - 1 (also reachable as -1). A result of 0 means the stack is empty.Parameters
T- Teascript state
Returns
The number of elements on the stack.
Example
tea_push_integer(T, 42);
tea_push_integer(T, 43);
int n = tea_get_top(T); /* n = 2 */
See also
tea_set_top
Signature
void tea_set_top(tea_State* T, int index);Description
Sets the stack top to index. If the new top is larger than the old one, the new slots are filled with nil. If it is smaller, the values above the new top are discarded.
...abc...atea_set_top(T, 0) empties the stack.
Parameters
T- Teascript state
index- New stack top
Example
/* assume the stack is empty */
tea_push_integer(T, 123); /* top = 1, [123] */
tea_set_top(T, 3); /* top = 3, [123, nil, nil] */
tea_set_top(T, 1); /* top = 1, [123] */
tea_set_top(T, 0); /* top = 0, [] */
See also
tea_pop
Signature
void tea_pop(tea_State* T, int n);Description
Removes n elements from the top of the stack.
...val1...valN...Parameters
T- Teascript state
n- Number of elements to pop
Example
tea_push_integer(T, 1);
tea_push_integer(T, 2);
tea_push_integer(T, 3); /* [1, 2, 3] */
tea_pop(T, 2); /* [1] */
See also
tea_push_value
Signature
void tea_push_value(tea_State* T, int index);Description
Pushes a copy of the value at index onto the top of the stack.
...val......val...valParameters
T- Teascript state
index- Stack index of the value to duplicate
Example
tea_push_string(T, "tea"); /* ["tea"] */
tea_push_value(T, -1); /* ["tea", "tea"] */
See also
tea_remove
Signature
void tea_remove(tea_State* T, int index);Description
Removes the value at index. The elements above index are shifted down to fill the gap.
...val(index).........Parameters
T- Teascript state
index- Stack index of the value to remove
Example
tea_push_integer(T, 123);
tea_push_integer(T, 453);
tea_push_integer(T, 987); /* [123, 453, 987] */
tea_remove(T, -2); /* [123, 987] */
See also
tea_insert
Signature
void tea_insert(tea_State* T, int index);Description
Moves the top value into position index, shifting up the elements at and above index.
...old(index)...val...val(index)old...A negative index is evaluated before the top value is popped.
Parameters
T- Teascript state
index- Stack index where the top value is inserted
Example
tea_push_string(T, "foo");
tea_push_string(T, "tea");
tea_push_integer(T, 698);
tea_push_string(T, "bar"); /* ["foo", "tea", 698, "bar"] */
tea_insert(T, -3); /* ["foo", "bar", "tea", 698] */
See also
tea_replace
Signature
void tea_replace(tea_State* T, int index);Description
Pops the top value and uses it to overwrite the value at index.
...old(index)...val...val(index)...A negative index is evaluated before the top value is popped.
Parameters
T- Teascript state
index- Stack index of the value to overwrite
Example
tea_push_integer(T, 123);
tea_push_integer(T, 897);
tea_push_integer(T, 769);
tea_push_string(T, "bar"); /* [123, 897, 769, "bar"] */
tea_replace(T, -3); /* [123, "bar", 769] */
See also
tea_copy
Signature
void tea_copy(tea_State* T, int from_index, int to_index);Description
Copies the value at from_index into to_index, overwriting the previous value there. The stack size does not change.
...old(to_index)...val(from_index)......val(to_index)...val(from_index)...This is shorthand for:
to_index = tea_absindex(T, to_index);
tea_push_value(T, from_index);
tea_replace(T, to_index);
Parameters
T- Teascript state
from_index- Stack index of the source value
to_index- Stack index of the destination slot
Example
tea_push_integer(T, 10);
tea_push_integer(T, 20);
tea_push_integer(T, 30);
tea_copy(T, -1, 0); /* [30, 20, 30] */
See also
tea_swap
Signature
void tea_swap(tea_State* T, int index1, int index2);Description
Swaps the values at index1 and index2. If both indices are the same, nothing happens.
...val1...val2......val2...val1...Parameters
T- Teascript state
index1- First stack index
index2- Second stack index
Example
tea_push_integer(T, 569);
tea_push_string(T, "foo");
tea_push_integer(T, 437);
tea_push_string(T, "bar");
tea_push_string(T, "tea"); /* [569, "foo", 437, "bar", "tea"] */
tea_swap(T, -3, -1); /* [569, "foo", "tea", "bar", 437] */
See also
tea_test_stack
Signature
bool tea_test_stack(tea_State* T, int size);Description
Checks whether the stack has room for at least size more elements, growing it if necessary. Returns true if the space is available and false otherwise; on failure the stack is left unchanged.
Unlike tea_check_stack, this function never raises an error, so it can be used to handle a potential stack overflow gracefully.
Parameters
T- Teascript state
size- Number of additional slots required
Returns
true if the stack can hold size more elements; false otherwise.
Example
if(!tea_test_stack(T, 4))
{
tea_error(T, "not enough stack space");
}
See also
tea_check_stack
Signature
void tea_check_stack(tea_State* T, int size, const char* msg);Description
Ensures the stack has room for at least size more elements, growing it if necessary. If the stack cannot grow enough, a stack overflow error is raised, using msg as part of its message.
Use tea_test_stack if you need to handle the failure yourself.
Parameters
T- Teascript state
size- Number of additional slots required
msg- Message included in the error if the check fails
Errors
Example
static void push_range(tea_State* T)
{
tea_Integer n = tea_check_integer(T, 1);
tea_check_stack(T, (int)n, "range too large");
for(tea_Integer i = 0; i < n; i++)
tea_push_integer(T, i);
}