Functions that read a value from the stack as a C value, when you already know its type. Unlike the tea_to_* functions, they do not convert, and unlike the tea_check_* functions, they do not produce friendly argument errors: using one on a value of the wrong type is a programming error and raises an internal API error. Test the type first with tea_get_type or the tea_is_* macros, or use the check functions to validate arguments.

tea_get_bool

Signature

bool tea_get_bool(tea_State* T, int index);
[-0, +0, e]

Description

Returns the boolean value at index. The value must be a boolean. To apply Teascript truthiness rules to any value, use tea_to_bool.

Parameters

T
Teascript state
index
Stack index of the value

Returns

The boolean value at index.

Errors

Raises an internal API error if the value is not a boolean.

Example

tea_push_true(T);
if(tea_get_bool(T, -1))
    printf("value is true\n");

See also

tea_to_bool, tea_check_bool, tea_is_bool

tea_get_number

Signature

tea_Number tea_get_number(tea_State* T, int index);
[-0, +0, e]

Description

Returns the number at index as a tea_Number (a double). The value must be a number.

Parameters

T
Teascript state
index
Stack index of the value

Returns

The number at index.

Errors

Raises an internal API error if the value is not a number.

Example

tea_push_number(T, 3.14159);
tea_Number pi = tea_get_number(T, -1);
printf("value %f\n", pi);

See also

tea_get_integer, tea_to_number, tea_check_number

tea_get_integer

Signature

tea_Integer tea_get_integer(tea_State* T, int index);
[-0, +0, e]

Description

Returns the number at index converted to a tea_Integer. The value must be a number; the fractional part is discarded (truncation toward zero).

Parameters

T
Teascript state
index
Stack index of the value

Returns

The number at index, truncated to a tea_Integer.

Errors

Raises an internal API error if the value is not a number.

Example

tea_push_number(T, 42.9);
tea_Integer n = tea_get_integer(T, -1);   /* n = 42 */
printf("int value %td\n", n);

See also

tea_get_number, tea_to_integer, tea_check_integer

tea_get_pointer

Signature

const void* tea_get_pointer(tea_State* T, int index);
[-0, +0, e]

Description

Returns the raw C pointer at index. The value must be a pointer (see tea_push_pointer), not a userdata.

Parameters

T
Teascript state
index
Stack index of the value

Returns

The pointer stored at index.

Errors

Raises an internal API error if the value is not a pointer.

Example

void* handle = get_some_handle();
tea_push_pointer(T, handle);
const void* ptr = tea_get_pointer(T, -1);
printf("my pointer is %p\n", ptr);

See also

tea_to_pointer, tea_check_pointer, tea_push_pointer

tea_get_range

Signature

void tea_get_range(tea_State* T, int index, tea_Number* start, tea_Number* end, tea_Number* step);
[-0, +0, e]

Description

Retrieves the components of the range at index. The value must be a range. Any of the output pointers may be NULL, in which case that component is not written.

Parameters

T
Teascript state
index
Stack index of the range
start
Receives the range start, or NULL
end
Receives the range end, or NULL
step
Receives the range step, or NULL

Errors

Raises an internal API error if the value is not a range.

Example

tea_push_range(T, 0, 10, 2);
tea_Number start, end, step;
tea_get_range(T, -1, &start, &end, &step);   /* 0, 10, 2 */

See also

tea_check_range, tea_push_range, tea_is_range

tea_get_lstring

Signature

const char* tea_get_lstring(tea_State* T, int index, size_t* len);
[-0, +0, e]

Description

Returns the string at index as a C string. The value must be a string. The pointer refers to the interpreter’s internal copy and stays valid as long as the string remains on the stack.

If len is not NULL, the string length is stored in *len. Teascript strings may contain embedded zero bytes, so use the length rather than relying on the terminator.

Note

The result is never NULL, even for an empty string.

Parameters

T
Teascript state
index
Stack index of the string
len
Receives the string length, or NULL

Returns

A pointer to the string data.

Errors

Raises an internal API error if the value is not a string.

Example

tea_push_lstring(T, "hello\0world", 11);
size_t len;
const char* s = tea_get_lstring(T, -1, &len);   /* len = 11 */
printf("%.*s\n", (int)len, s);

See also

tea_get_string, tea_to_lstring, tea_check_lstring

tea_get_string

Signature

const char* tea_get_string(tea_State* T, int index);
[-0, +0, e]

Description

Returns the string at index as a C string. The value must be a string. Equivalent to tea_get_lstring(T, index, NULL).

Because strings may contain embedded zero bytes, use tea_get_lstring when you need the real length.

Parameters

T
Teascript state
index
Stack index of the string

Returns

A pointer to the string data.

Errors

Raises an internal API error if the value is not a string.

Example

tea_push_string(T, "tea");
const char* name = tea_get_string(T, -1);   /* "tea" */

See also

tea_get_lstring, tea_to_string, tea_check_string

tea_get_userdata

Signature

void* tea_get_userdata(tea_State* T, int index);
[-0, +0, e]

Description

Returns a pointer to the data block of the userdata at index. The value must be a userdata. Unlike tea_check_udata, this does not verify the userdata’s class.

Parameters

T
Teascript state
index
Stack index of the userdata

Returns

A pointer to the userdata’s data block.

Errors

Raises an internal API error if the value is not a userdata.

Example

MyBuffer* buf = (MyBuffer*)tea_new_userdata(T, sizeof(MyBuffer));
/* ... */
MyBuffer* same = (MyBuffer*)tea_get_userdata(T, -1);   /* same == buf */

See also

tea_to_userdata, tea_check_userdata, tea_test_udata, tea_new_userdata

tea_get_udvalue

Signature

bool tea_get_udvalue(tea_State* T, int ud, int n);
[-0, +1, -]

Description

Pushes the n-th user value of the userdata at ud, as created with tea_new_userdatav or tea_new_udatav. User values start out as nil and are set with tea_set_udvalue.

Returns true if the user value exists and was pushed; returns false and pushes nothing if n is out of range.

Parameters

T
Teascript state
ud
Stack index of the userdata
n
Zero-based number of the user value

Returns

true if the value was pushed; false otherwise.

Example

tea_new_userdatav(T, sizeof(int), 2);   /* two user values */
tea_push_string(T, "tag");
tea_set_udvalue(T, -2, 0);              /* user value 0 = "tag" */

if(tea_get_udvalue(T, -1, 0))
    printf("%s\n", tea_get_string(T, -1));   /* tag */
tea_pop(T, 1);

See also

tea_set_udvalue, tea_new_userdatav, tea_new_udatav