The type codes and masks used by the C API, and the functions and macros that inspect the type of a value on the stack or compare two values. None of them raise errors on a type mismatch: they only report. To validate arguments and raise an error instead, see the Argument Checking section.

An index that holds no value (past the top of the stack) has type TEA_TYPE_NONE, which is different from the Teascript value nil (TEA_TYPE_NIL).

TEA_TYPE_NONE

Signature

enum
{
    TEA_TYPE_NONE,
    TEA_TYPE_NIL,
    TEA_TYPE_BOOL,
    TEA_TYPE_NUMBER,
    TEA_TYPE_POINTER,
    TEA_TYPE_STRING,
    TEA_TYPE_RANGE,
    TEA_TYPE_FUNCTION,
    TEA_TYPE_MODULE,
    TEA_TYPE_CLASS,
    TEA_TYPE_INSTANCE,
    TEA_TYPE_LIST,
    TEA_TYPE_MAP,
    TEA_TYPE_USERDATA,
};

Description

The codes returned by tea_get_type and accepted by tea_check_type. The values are consecutive, starting at 0.

CodeValue
TEA_TYPE_NONENo value (empty or invalid index)
TEA_TYPE_NILnil
TEA_TYPE_BOOLBoolean
TEA_TYPE_NUMBERNumber
TEA_TYPE_POINTERRaw C pointer
TEA_TYPE_STRINGString
TEA_TYPE_RANGERange
TEA_TYPE_FUNCTIONFunction
TEA_TYPE_MODULEModule
TEA_TYPE_CLASSClass
TEA_TYPE_INSTANCEClass instance
TEA_TYPE_LISTList
TEA_TYPE_MAPMap
TEA_TYPE_USERDATAUserdata

Example

switch(tea_get_type(T, 1))
{
    case TEA_TYPE_NUMBER: /* ... */ break;
    case TEA_TYPE_STRING: /* ... */ break;
    default:              /* ... */ break;
}

See also

tea_get_type, tea_check_type, TEA_MASK_NONE

TEA_MASK_NONE

Signature

#define TEA_MASK_<TYPE> (1 << TEA_TYPE_<TYPE>)

Description

One bit mask per basic type, each defined as 1 << TEA_TYPE_x: TEA_MASK_NONE, TEA_MASK_NIL, TEA_MASK_BOOL, TEA_MASK_NUMBER, TEA_MASK_POINTER, TEA_MASK_STRING, TEA_MASK_RANGE, TEA_MASK_FUNCTION, TEA_MASK_MODULE, TEA_MASK_CLASS, TEA_MASK_INSTANCE, TEA_MASK_LIST, TEA_MASK_MAP and TEA_MASK_USERDATA.

Masks can be combined with | and tested against a value with tea_is_mask, which makes it easy to accept several types at once.

Example

/* accept a list or a map */
if(!tea_is_mask(T, 1, TEA_MASK_LIST | TEA_MASK_MAP))
    tea_type_error(T, 1, "list or map");

See also

tea_get_mask, tea_is_mask, TEA_TYPE_NONE

tea_typeof

Signature

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

Description

Returns the name of the type of the value at index as a NUL-terminated C string (for example "number", "string" or "list"). If the index holds no value, the string "no value" is returned.

The string belongs to the interpreter and must not be modified. It is meant for diagnostics, error messages and debugging output.

Parameters

T
Teascript state
index
Stack index of the value

Returns

The type name of the value at index.

Example

tea_push_number(T, 1);
printf("%s\n", tea_typeof(T, -1));   /* number */

See also

tea_get_type, tea_type_error

tea_get_type

Signature

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

Description

Returns the type of the value at index as one of the TEA_TYPE_* constants. If the index holds no value, TEA_TYPE_NONE is returned.

Parameters

T
Teascript state
index
Stack index of the value

Returns

One of the TEA_TYPE_* constants.

Example

tea_push_nil(T);
int t = tea_get_type(T, -1);   /* TEA_TYPE_NIL */
t = tea_get_type(T, 5);        /* TEA_TYPE_NONE: no value at index 5 */

See also

tea_get_mask, tea_typeof, TEA_TYPE_NONE

tea_get_mask

Signature

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

Description

Returns the type mask of the value at index, the TEA_MASK_* constant that corresponds to its type. This is 1 << tea_get_type(T, index).

Parameters

T
Teascript state
index
Stack index of the value

Returns

One of the TEA_MASK_* constants.

Example

tea_push_string(T, "tea");
if(tea_get_mask(T, -1) & (TEA_MASK_STRING | TEA_MASK_NUMBER))
{
    /* a string or a number */
}

See also

tea_is_mask, tea_get_type, TEA_MASK_NONE

tea_is_object

Signature

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

Description

Returns true if the value at index is a garbage-collected object, as opposed to a plain value such as nil, a boolean, a number or a raw pointer.

Parameters

T
Teascript state
index
Stack index of the value

Returns

true if the value is an object; false otherwise, including for an invalid index.

Example

tea_push_string(T, "tea");
tea_push_number(T, 1);
bool a = tea_is_object(T, -2);   /* true */
bool b = tea_is_object(T, -1);   /* false */

See also

tea_get_type, tea_gc

tea_is_cfunction

Signature

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

Description

Returns true if the value at index is a C function, that is, one created with tea_push_cfunction, tea_push_cclosure or one of the registration helpers. Functions written in Teascript are not C functions.

Parameters

T
Teascript state
index
Stack index of the value

Returns

true if the value is a C function; false otherwise.

Example

tea_push_cfunction(T, my_func, 0, 0);
bool c = tea_is_cfunction(T, -1);   /* true */

See also

tea_to_cfunction, tea_check_cfunction, tea_push_cfunction

tea_equal

Signature

bool tea_equal(tea_State* T, int index1, int index2);
[-0, +0, e]

Description

Returns true if the values at index1 and index2 are equal according to the == operator of Teascript, which may call an equality method. Use tea_rawequal to compare without calling any method.

Parameters

T
Teascript state
index1
Stack index of the first value
index2
Stack index of the second value

Returns

true if the values are equal; false otherwise.

Example

tea_push_integer(T, 3);
tea_push_number(T, 3.0);
bool eq = tea_equal(T, -2, -1);   /* true */

See also

tea_rawequal

tea_rawequal

Signature

bool tea_rawequal(tea_State* T, int index1, int index2);
[-0, +0, -]

Description

Returns true if the values at index1 and index2 are primitively equal, without calling any equality method. Returns false if either index is invalid.

Parameters

T
Teascript state
index1
Stack index of the first value
index2
Stack index of the second value

Returns

true if the values are raw-equal; false otherwise.

Example

tea_push_string(T, "tea");
tea_push_string(T, "tea");
bool eq = tea_rawequal(T, -2, -1);   /* true */

See also

tea_equal

tea_is_mask

Signature

#define tea_is_mask(T, n, m) (tea_get_mask(T, (n)) & (m))
[-0, +0, -]

Description

Tests whether the type of the value at n is one of the types in the mask m. The result is the masked value, so it is non-zero when the test passes; it is not necessarily 1.

Parameters

T
Teascript state
n
Stack index of the value
m
Mask of accepted types (TEA_MASK_*, combined with |)

Returns

Non-zero if the value’s type is in the mask; 0 otherwise.

Example

if(tea_is_mask(T, 1, TEA_MASK_LIST | TEA_MASK_MAP))
{
    /* argument 1 is a list or a map */
}

See also

tea_get_mask, TEA_MASK_NONE

tea_is_nonenil

Signature

#define tea_is_nonenil(T, n) (tea_get_type(T, (n)) <= TEA_TYPE_NIL)
[-0, +0, -]

Description

Tests whether the value at n is absent or nil. This is handy for optional arguments, where both mean “not given”.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the index holds no value or nil.

Example

if(tea_is_nonenil(T, 2))
{
    /* optional argument 2 was not given */
}

See also

tea_is_none, tea_is_nil, tea_opt_nil

tea_is_none

Signature

#define tea_is_none(T, n) (tea_get_type(T, (n)) == TEA_TYPE_NONE)
[-0, +0, -]

Description

Tests whether the index n holds no value, as opposed to holding nil.

Parameters

T
Teascript state
n
Stack index to test

Returns

true if the index holds no value.

Example

if(tea_is_none(T, 3))
{
    /* fewer than four values on the stack */
}

See also

tea_is_nil, tea_is_nonenil

tea_is_nil

Signature

#define tea_is_nil(T, n) (tea_get_type(T, (n)) == TEA_TYPE_NIL)
[-0, +0, -]

Description

Tests whether the value at n is nil. An index that holds no value is not nil; use tea_is_nonenil to test for both.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is nil.

Example

tea_push_nil(T);
bool n = tea_is_nil(T, -1);   /* true */

See also

tea_is_none, tea_is_nonenil, tea_push_nil

tea_is_bool

Signature

#define tea_is_bool(T, n) (tea_get_type(T, (n)) == TEA_TYPE_BOOL)
[-0, +0, -]

Description

Tests whether the value at n is a boolean.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a boolean.

Example

tea_push_true(T);
bool b = tea_is_bool(T, -1);   /* true */

See also

tea_get_bool, tea_to_bool, tea_check_bool

tea_is_number

Signature

#define tea_is_number(T, n) (tea_get_type(T, (n)) == TEA_TYPE_NUMBER)
[-0, +0, -]

Description

Tests whether the value at n is a number. Strings that look like numbers do not count; use tea_to_numberx to convert them.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a number.

Example

tea_push_number(T, 3.5);
bool b = tea_is_number(T, -1);   /* true */

See also

tea_get_number, tea_to_numberx, tea_check_number

tea_is_pointer

Signature

#define tea_is_pointer(T, n) (tea_get_type(T, (n)) == TEA_TYPE_POINTER)
[-0, +0, -]

Description

Tests whether the value at n is a raw C pointer, as pushed with tea_push_pointer. A userdata is not a pointer.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a raw pointer.

Example

int x;
tea_push_pointer(T, &x);
bool b = tea_is_pointer(T, -1);   /* true */

See also

tea_get_pointer, tea_push_pointer, tea_check_pointer

tea_is_range

Signature

#define tea_is_range(T, n) (tea_get_type(T, (n)) == TEA_TYPE_RANGE)
[-0, +0, -]

Description

Tests whether the value at n is a range.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a range.

Example

tea_push_range(T, 0, 10, 1);
bool b = tea_is_range(T, -1);   /* true */

See also

tea_get_range, tea_push_range, tea_check_range

tea_is_string

Signature

#define tea_is_string(T, n) (tea_get_type(T, (n)) == TEA_TYPE_STRING)
[-0, +0, -]

Description

Tests whether the value at n is a string. Numbers are not strings; use tea_to_string to convert them.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a string.

Example

tea_push_string(T, "tea");
bool b = tea_is_string(T, -1);   /* true */

See also

tea_get_string, tea_to_string, tea_check_string

tea_is_list

Signature

#define tea_is_list(T, n) (tea_get_type(T, (n)) == TEA_TYPE_LIST)
[-0, +0, -]

Description

Tests whether the value at n is a list.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a list.

Example

tea_new_list(T, 0);
bool b = tea_is_list(T, -1);   /* true */

See also

tea_new_list, tea_check_list

tea_is_map

Signature

#define tea_is_map(T, n) (tea_get_type(T, (n)) == TEA_TYPE_MAP)
[-0, +0, -]

Description

Tests whether the value at n is a map.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a map.

Example

tea_new_map(T);
bool b = tea_is_map(T, -1);   /* true */

See also

tea_new_map, tea_check_map

tea_is_function

Signature

#define tea_is_function(T, n) (tea_get_type(T, (n)) == TEA_TYPE_FUNCTION)
[-0, +0, -]

Description

Tests whether the value at n is a function. Use tea_is_cfunction to tell C functions apart.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a function.

Example

if(tea_get_global(T, "print") && tea_is_function(T, -1))
{
    /* print is callable */
}

See also

tea_is_cfunction, tea_check_function

tea_is_module

Signature

#define tea_is_module(T, n) (tea_get_type(T, (n)) == TEA_TYPE_MODULE)
[-0, +0, -]

Description

Tests whether the value at n is a module.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a module.

Example

tea_import(T, "math");
bool b = tea_is_module(T, -1);   /* true */

See also

tea_new_module, tea_check_module

tea_is_class

Signature

#define tea_is_class(T, n) (tea_get_type(T, (n)) == TEA_TYPE_CLASS)
[-0, +0, -]

Description

Tests whether the value at n is a class. An instance of a class is not a class; see tea_is_instance.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a class.

Example

tea_new_class(T, "Point");
bool b = tea_is_class(T, -1);   /* true */

See also

tea_is_instance, tea_new_class, tea_check_class

tea_is_instance

Signature

#define tea_is_instance(T, n) (tea_get_type(T, (n)) == TEA_TYPE_INSTANCE)
[-0, +0, -]

Description

Tests whether the value at n is an instance of a class.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a class instance.

Example

if(tea_is_instance(T, 0))
{
    /* argument 0 is a class instance */
}

See also

tea_is_class, tea_check_instance

tea_is_userdata

Signature

#define tea_is_userdata(T, n) (tea_get_type(T, (n)) == TEA_TYPE_USERDATA)
[-0, +0, -]

Description

Tests whether the value at n is a userdata. To also check its class, use tea_test_udata.

Parameters

T
Teascript state
n
Stack index of the value

Returns

true if the value is a userdata.

Example

tea_new_userdata(T, 16);
bool b = tea_is_userdata(T, -1);   /* true */

See also

tea_get_userdata, tea_test_udata, tea_check_userdata