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 20

Description

The number of free stack slots guaranteed to a C function when it starts running. A function that pushes more values than this must reserve the extra space first with 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_check_stack, tea_test_stack

TEA_REGISTRY_INDEX

Signature

#define TEA_REGISTRY_INDEX (-10000)

Description

Pseudo-index that refers to the registry, a table reserved for use by C code. It is not a real stack slot, but it is accepted by functions that take an index.

See also

TEA_UPVALUES_INDEX, tea_absindex

TEA_UPVALUES_INDEX

Signature

#define TEA_UPVALUES_INDEX (-11000)

Description

Base of the pseudo-indices that refer to the upvalues of the running C closure. Use tea_upvalue_index rather than this value directly.

See also

tea_upvalue_index, tea_push_cclosure

tea_upvalue_index

Signature

#define tea_upvalue_index(i) (TEA_UPVALUES_INDEX - (i))

Description

Produces the pseudo-index of upvalue 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_push_cclosure, TEA_UPVALUES_INDEX

tea_absindex

Signature

int tea_absindex(tea_State* T, int index);
[-0, +0, -]

Description

Converts the acceptable index 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, tea_set_top

tea_get_top

Signature

int tea_get_top(tea_State* T);
[-0, +0, -]

Description

Returns the number of elements in the current frame. Because indices are zero-based, the top element is at index 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, tea_absindex

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
...a

tea_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, tea_get_top

tea_pop

Signature

void tea_pop(tea_State* T, int n);
[-n, +0, -]

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_set_top, tea_remove

tea_push_value

Signature

void tea_push_value(tea_State* T, int index);
[-0, +1, -]

Description

Pushes a copy of the value at index onto the top of the stack.

...val...
...val...val

Parameters

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_copy, tea_replace

tea_remove

Signature

void tea_remove(tea_State* T, int index);
[-1, +0, -]

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, tea_pop

tea_insert

Signature

void tea_insert(tea_State* T, int index);
[-1, +1, -]

Description

Moves the top value into position index, shifting up the elements at and above index.

...old(index)...val
...val(index)old...
Note

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_remove, tea_replace

tea_replace

Signature

void tea_replace(tea_State* T, int index);
[-1, +0, -]

Description

Pops the top value and uses it to overwrite the value at index.

...old(index)...val
...val(index)...
Note

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, tea_insert

tea_copy

Signature

void tea_copy(tea_State* T, int from_index, int to_index);
[-0, +0, -]

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_push_value, tea_replace

tea_swap

Signature

void tea_swap(tea_State* T, int index1, int index2);
[-0, +0, -]

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_copy, tea_replace

tea_test_stack

Signature

bool tea_test_stack(tea_State* T, int size);
[-0, +0, m]

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, tea_get_top, TEA_MIN_STACK

tea_check_stack

Signature

void tea_check_stack(tea_State* T, int size, const char* msg);
[-0, +0, v]

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

Raises a runtime error (stack overflow) if the requested space is not available.

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);
}

See also

tea_test_stack, tea_get_top, TEA_MIN_STACK