Functions for validating the arguments received by a C function. Each tea_check_* function verifies the value at index and returns it as a C value; if the check fails, a bad argument error that names the offending argument is raised, so a C function can validate all its arguments at the top and then work with plain C values.

These functions raise errors and never return on failure. For a non-raising test, use the tea_is_* macros or tea_test_udata; for arguments that may be absent, see the Optional Arguments section; for values you already know have the right type, see the Get Functions section.

tea_check_type

Signature

void tea_check_type(tea_State* T, int index, int type);
[-0, +0, v]

Description

Checks that the value at index has exactly the type type, one of the TEA_TYPE_* constants.

Parameters

T
Teascript state
index
Stack index of the argument
type
Expected type (TEA_TYPE_*)

Errors

Raises a type error if the value does not have the expected type.

Example

/* argument 1 must be a list */
tea_check_type(T, 1, TEA_TYPE_LIST);

See also

tea_check_any, tea_get_type, tea_is_mask

tea_check_any

Signature

void tea_check_any(tea_State* T, int index);
[-0, +0, v]

Description

Checks that there is a value at index, of any type. A nil value is accepted; only a missing argument fails.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises an argument error if index holds no value.

Example

tea_check_any(T, 1);   /* argument 1 is required, but may be nil */

See also

tea_check_type, tea_opt_nil, tea_is_none

tea_check_bool

Signature

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

Description

Checks that the value at index is a boolean and returns it.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

The boolean value at index.

Errors

Raises a type error if the value is not a boolean.

Example

bool verbose = tea_check_bool(T, 1);

See also

tea_opt_bool, tea_get_bool, tea_to_bool

tea_check_number

Signature

tea_Number tea_check_number(tea_State* T, int index);
[-0, +0, v]

Description

Checks that the value at index is a number and returns it.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

The numeric value at index.

Errors

Raises a type error if the value is not a number.

Example

tea_Number radius = tea_check_number(T, 1);

See also

tea_check_integer, tea_opt_number, tea_get_number

tea_check_integer

Signature

tea_Integer tea_check_integer(tea_State* T, int index);
[-0, +0, v]

Description

Checks that the value at index is a number and returns it truncated to a tea_Integer. The fractional part is discarded, so 2.9 gives 2.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

The integer value at index.

Errors

Raises a type error if the value is not a number.

Example

tea_Integer count = tea_check_integer(T, 2);

See also

tea_check_number, tea_opt_integer, tea_get_integer

tea_check_pointer

Signature

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

Description

Checks that the value at index is a raw C pointer and returns it.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

The pointer at index.

Errors

Raises a type error if the value is not a pointer.

Example

const void* ctx = tea_check_pointer(T, 1);

See also

tea_opt_pointer, tea_get_pointer, tea_push_pointer

tea_check_range

Signature

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

Description

Checks that the value at index is a range and stores its components in start, end and step.

Parameters

T
Teascript state
index
Stack index of the argument
start
Receives the range start
end
Receives the range end
step
Receives the range step

Errors

Raises a type error if the value is not a range.

Example

tea_Number start, end, step;
tea_check_range(T, 1, &start, &end, &step);

See also

tea_get_range, tea_push_range

tea_check_lstring

Signature

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

Description

Checks that the value at index is a string and returns a pointer to its data. If len is not NULL, the string length is stored in *len. Use the length: Teascript strings may contain embedded zero bytes.

The pointer is valid as long as the string stays on the stack.

Parameters

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

Returns

A pointer to the string data.

Errors

Raises a type error if the value is not a string.

Example

size_t len;
const char* data = tea_check_lstring(T, 1, &len);

See also

tea_check_string, tea_opt_lstring, tea_get_lstring

tea_check_string

Signature

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

Description

Checks that the value at index is a string and returns a pointer to its data. Equivalent to tea_check_lstring(T, index, NULL). Use tea_check_lstring if the string may contain embedded zero bytes.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

A pointer to the string data.

Errors

Raises a type error if the value is not a string.

Example

const char* path = tea_check_string(T, 1);

See also

tea_check_lstring, tea_opt_string, tea_get_string

tea_check_cfunction

Signature

tea_CFunction tea_check_cfunction(tea_State* T, int index);
[-0, +0, v]

Description

Checks that the value at index is a C function and returns its function pointer.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

The tea_CFunction stored in the value.

Errors

Raises a type error if the value is not a C function.

Example

tea_CFunction cb = tea_check_cfunction(T, 2);

See also

tea_opt_cfunction, tea_is_cfunction, tea_to_cfunction

tea_check_userdata

Signature

void* tea_check_userdata(tea_State* T, int index);
[-0, +0, v]

Description

Checks that the value at index is a userdata, of any class, and returns a pointer to its data block. To require a particular class, use tea_check_udata.

Parameters

T
Teascript state
index
Stack index of the argument

Returns

A pointer to the userdata’s data block.

Errors

Raises a type error if the value is not a userdata.

Example

void* block = tea_check_userdata(T, 1);

See also

tea_check_udata, tea_opt_userdata, tea_get_userdata

tea_check_udata

Signature

void* tea_check_udata(tea_State* T, int idx, const char* name);
[-0, +0, v]

Description

Checks that the value at idx is a userdata whose class is the one registered under name, and returns a pointer to its data block. This is the safe way to receive a userdata created with tea_new_udata or tea_new_udatav.

Parameters

T
Teascript state
idx
Stack index of the argument
name
Name the userdata class was registered with

Returns

A pointer to the userdata’s data block.

Errors

Raises a type error naming name if the value is not a userdata of that class.

Example

Socket* s = (Socket*)tea_check_udata(T, 1, "Socket");

See also

tea_test_udata, tea_new_udata, tea_check_userdata

tea_test_udata

Signature

void* tea_test_udata(tea_State* T, int idx, const char* name);
[-0, +0, -]

Description

Tests whether the value at idx is a userdata whose class is the one registered under name. If so, returns a pointer to its data block; otherwise returns NULL.

This is the non-raising counterpart of tea_check_udata, useful for optional or polymorphic arguments.

Parameters

T
Teascript state
idx
Stack index of the value
name
Name the userdata class was registered with

Returns

A pointer to the data block on success; NULL otherwise.

Example

void* ring = tea_test_udata(T, 1, "RingBuffer");
if(ring)
{
    /* argument 1 is a RingBuffer */
}

See also

tea_check_udata, tea_new_udata, tea_type_error

tea_check_option

Signature

int tea_check_option(tea_State* T, int index, const char* def, const char* const options[]);
[-0, +0, v]

Description

Checks that the value at index is a string equal to one of the strings in options, which must be terminated by NULL, and returns its position in the array. If the argument is absent and def is not NULL, def is used in its place.

It is the usual way to map a string argument to a C enum.

Parameters

T
Teascript state
index
Stack index of the argument
def
Default option used when the argument is absent, or NULL for none
options
NULL-terminated array of accepted strings

Returns

The index in options of the selected string.

Errors

Raises an argument error if the value is not a string, or is not one of the options.

Example

static const char* const modes[] = { "read", "write", "append", NULL };

static void open_file(tea_State* T)
{
    const char* path = tea_check_string(T, 1);
    int mode = tea_check_option(T, 2, "read", modes);   /* 0, 1 or 2 */
    /* ... */
}

See also

tea_check_string, tea_opt_string

tea_check_list

Signature

#define tea_check_list(T, index) tea_check_type(T, (index), TEA_TYPE_LIST)
[-0, +0, v]

Description

Checks that the value at index is a list. Shorthand for tea_check_type with TEA_TYPE_LIST.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises a type error if the value is not a list.

Example

tea_check_list(T, 1);

See also

tea_check_type, tea_is_list

tea_check_map

Signature

#define tea_check_map(T, index) tea_check_type(T, (index), TEA_TYPE_MAP)
[-0, +0, v]

Description

Checks that the value at index is a map. Shorthand for tea_check_type with TEA_TYPE_MAP.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises a type error if the value is not a map.

Example

tea_check_map(T, 1);

See also

tea_check_type, tea_is_map

tea_check_function

Signature

#define tea_check_function(T, index) tea_check_type(T, (index), TEA_TYPE_FUNCTION)
[-0, +0, v]

Description

Checks that the value at index is a function. Shorthand for tea_check_type with TEA_TYPE_FUNCTION.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises a type error if the value is not a function.

Example

tea_check_function(T, 1);   /* a callback */

See also

tea_check_type, tea_is_function

tea_check_module

Signature

#define tea_check_module(T, index) tea_check_type(T, (index), TEA_TYPE_MODULE)
[-0, +0, v]

Description

Checks that the value at index is a module. Shorthand for tea_check_type with TEA_TYPE_MODULE.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises a type error if the value is not a module.

Example

tea_check_module(T, 1);

See also

tea_check_type, tea_is_module

tea_check_class

Signature

#define tea_check_class(T, index) tea_check_type(T, (index), TEA_TYPE_CLASS)
[-0, +0, v]

Description

Checks that the value at index is a class. Shorthand for tea_check_type with TEA_TYPE_CLASS.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises a type error if the value is not a class.

Example

tea_check_class(T, 1);

See also

tea_check_type, tea_is_class

tea_check_instance

Signature

#define tea_check_instance(T, index) tea_check_type(T, (index), TEA_TYPE_INSTANCE)
[-0, +0, v]

Description

Checks that the value at index is a class instance. Shorthand for tea_check_type with TEA_TYPE_INSTANCE.

Parameters

T
Teascript state
index
Stack index of the argument

Errors

Raises a type error if the value is not an instance.

Example

tea_check_instance(T, 0);

See also

tea_check_type, tea_is_instance