Functions that push a C value onto the stack, converting it into a Teascript value. Each pushes exactly one value. The ones that create objects (strings, ranges, closures) may need to allocate memory, and can raise a memory error.

tea_push_nil

Signature

void tea_push_nil(tea_State* T);
[-0, +1, -]

Description

Pushes nil onto the stack.

Parameters

T
Teascript state

Example

tea_push_nil(T);   /* [nil] */

See also

tea_push_bool, tea_is_nil

tea_push_true

Signature

void tea_push_true(tea_State* T);
[-0, +1, -]

Description

Pushes the boolean true onto the stack. Equivalent to tea_push_bool(T, true).

Parameters

T
Teascript state

Example

tea_push_true(T);   /* [true] */

See also

tea_push_false, tea_push_bool

tea_push_false

Signature

void tea_push_false(tea_State* T);
[-0, +1, -]

Description

Pushes the boolean false onto the stack. Equivalent to tea_push_bool(T, false).

Parameters

T
Teascript state

Example

tea_push_false(T);   /* [false] */

See also

tea_push_true, tea_push_bool

tea_push_bool

Signature

void tea_push_bool(tea_State* T, bool b);
[-0, +1, -]

Description

Pushes a boolean onto the stack: true if b is non-zero, false otherwise.

Parameters

T
Teascript state
b
Boolean value to push

Example

tea_push_bool(T, false);   /* [false] */
tea_push_bool(T, true);    /* [false, true] */

See also

tea_push_true, tea_push_false, tea_get_bool

tea_push_number

Signature

void tea_push_number(tea_State* T, tea_Number n);
[-0, +1, -]

Description

Pushes a number (an IEEE 754 double) onto the stack.

If n is a NaN, it may be normalized into another NaN.

Parameters

T
Teascript state
n
Number to push

Example

tea_push_number(T, 547.98);

See also

tea_push_integer, tea_get_number

tea_push_integer

Signature

void tea_push_integer(tea_State* T, tea_Integer n);
[-0, +1, -]

Description

Pushes an integer onto the stack. Teascript has a single number type, so the integer is stored as a double and very large values may lose precision.

Parameters

T
Teascript state
n
Integer to push

Example

tea_push_integer(T, 987);

See also

tea_push_number, tea_get_integer

tea_push_pointer

Signature

void tea_push_pointer(tea_State* T, void* p);
[-0, +1, -]

Description

Pushes a raw C pointer onto the stack. The garbage collector does not manage it: the memory it points to must be kept alive by the caller. To tie memory to the lifetime of a Teascript value, use a userdata instead.

Parameters

T
Teascript state
p
Pointer to push

Example

int data = 42;
tea_push_pointer(T, &data);   /* [pointer] */

See also

tea_get_pointer, tea_new_userdata

tea_push_lstring

Signature

const char* tea_push_lstring(tea_State* T, const char* s, size_t len);
[-0, +1, m]

Description

Pushes the string made of the len bytes at s onto the stack. The bytes are copied, so s need not stay valid. Unlike tea_push_string, the string may contain embedded zero bytes.

Parameters

T
Teascript state
s
Pointer to the string data
len
Length of the string in bytes

Returns

A pointer to the internal copy of the string.

Errors

May raise a memory error.

Example

tea_push_lstring(T, "foo\0bar", 7);   /* ["foo\0bar"] */

See also

tea_push_string, tea_push_fstring, tea_push_literal

tea_push_string

Signature

const char* tea_push_string(tea_State* T, const char* s);
[-0, +1, m]

Description

Pushes the NUL-terminated C string s onto the stack. The length is found with strlen, and the bytes are copied.

Use tea_push_lstring if the string may contain embedded zero bytes.

Parameters

T
Teascript state
s
NUL-terminated string

Returns

A pointer to the internal copy of the string.

Errors

May raise a memory error.

Example

tea_push_string(T, "foo");       /* ["foo"] */
tea_push_string(T, "foo\0bar");  /* ["foo", "foo"]: stops at the first zero */
tea_push_string(T, "");          /* ["foo", "foo", ""] */

See also

tea_push_lstring, tea_push_fstring, tea_push_literal

tea_push_fstring

Signature

const char* tea_push_fstring(tea_State* T, const char* fmt, ...);
[-0, +1, m]

Description

Pushes a string built from a printf-style format string and the following arguments. Only a limited subset of printf specifiers is supported. Equivalent to calling tea_push_vfstring with a va_list of the arguments.

Parameters

T
Teascript state
fmt
Format string (limited printf-like syntax)
...
Arguments for the format specifiers

Returns

A pointer to the internal copy of the string.

Errors

May raise a memory error.

Example

tea_push_fstring(T, "Hello, %s! You have %d messages.", "Alice", 5);
/* ["Hello, Alice! You have 5 messages."] */

See also

tea_push_vfstring, tea_push_string, tea_error

tea_push_vfstring

Signature

const char* tea_push_vfstring(tea_State* T, const char* fmt, va_list args);
[-0, +1, m]

Description

Same as tea_push_fstring, but takes its arguments as a va_list. Use it to build your own variadic formatting functions.

Parameters

T
Teascript state
fmt
Format string (limited printf-like syntax)
args
va_list with the arguments

Returns

A pointer to the internal copy of the string.

Errors

May raise a memory error.

Example

static void push_log(tea_State* T, const char* fmt, ...)
{
    va_list args;
    va_start(args, fmt);
    tea_push_vfstring(T, fmt, args);
    va_end(args);
}

See also

tea_push_fstring

tea_push_literal

Signature

#define tea_push_literal(T, s) tea_push_lstring(T, "" s, (sizeof(s)/sizeof(char))-1)
[-0, +1, m]

Description

Pushes a C string literal onto the stack. The length is computed at compile time, so no strlen is needed. It only works with literals (the "" s trick makes the compiler reject anything else).

Parameters

T
Teascript state
s
String literal

Returns

A pointer to the internal copy of the string.

Errors

May raise a memory error.

Example

tea_push_literal(T, "hello");

See also

tea_push_lstring, tea_push_string

tea_push_range

Signature

void tea_push_range(tea_State* T, tea_Number start, tea_Number end, tea_Number step);
[-0, +1, m]

Description

Pushes a range onto the stack. A range is a numeric sequence defined by a start, an end and a step increment.

Parameters

T
Teascript state
start
First value of the range
end
End value of the range
step
Increment between values

Errors

May raise a memory error.

Example

tea_push_range(T, 1, 10, 2);    /* 1 to 10, step 2 */
tea_push_range(T, 0, 1, 0.1);   /* 0 to 1, step 0.1 */

See also

tea_get_range, tea_check_range

tea_push_cclosure

Signature

void tea_push_cclosure(tea_State* T, tea_CFunction fn, int nupvalues, int nargs, int nopts);
[-nupvalues, +1, m]

Description

Pushes a new C closure onto the stack: a C function together with a set of upvalues. The top nupvalues values of the stack are popped and stored as the closure’s upvalues, which the function reads with tea_upvalue_index.

nargs is the number of required arguments and nopts the number of optional ones. Use TEA_VARG for a variadic function.

Parameters

T
Teascript state
fn
C function called when the closure is invoked
nupvalues
Number of values to pop from the stack as upvalues
nargs
Number of required arguments, or TEA_VARG
nopts
Number of optional arguments

Errors

May raise a memory error.

Example

tea_push_integer(T, 100);   /* upvalue 1 */
tea_push_integer(T, 200);   /* upvalue 2 */
tea_push_cclosure(T, my_func, 2, 1, 0);
/* [cclosure] holding the upvalues 100 and 200 */

See also

tea_push_cfunction, tea_upvalue_index, tea_set_funcs

tea_push_cfunction

Signature

void tea_push_cfunction(tea_State* T, tea_CFunction fn, int nargs, int nopts);
[-0, +1, m]

Description

Pushes a C function onto the stack. Equivalent to tea_push_cclosure with no upvalues.

nargs is the number of required arguments and nopts the number of optional ones. Use TEA_VARG for a variadic function.

Parameters

T
Teascript state
fn
C function to push
nargs
Number of required arguments, or TEA_VARG
nopts
Number of optional arguments

Errors

May raise a memory error.

Example

tea_push_cfunction(T, my_func, 2, 1);   /* two required arguments, one optional */
tea_set_global(T, "my_func");

See also

tea_push_cclosure, tea_set_funcs, tea_is_cfunction