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);Description
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
Example
/* argument 1 must be a list */
tea_check_type(T, 1, TEA_TYPE_LIST);
See also
tea_check_any
Signature
void tea_check_any(tea_State* T, int index);Description
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
index holds no value.Example
tea_check_any(T, 1); /* argument 1 is required, but may be nil */
See also
tea_check_bool
Signature
bool tea_check_bool(tea_State* T, int index);Description
index is a boolean and returns it.Parameters
T- Teascript state
index- Stack index of the argument
Returns
The boolean value at index.
Errors
Example
bool verbose = tea_check_bool(T, 1);
See also
tea_check_number
Signature
tea_Number tea_check_number(tea_State* T, int index);Description
index is a number and returns it.Parameters
T- Teascript state
index- Stack index of the argument
Returns
The numeric value at index.
Errors
Example
tea_Number radius = tea_check_number(T, 1);
See also
tea_check_integer
Signature
tea_Integer tea_check_integer(tea_State* T, int index);Description
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
Example
tea_Integer count = tea_check_integer(T, 2);
See also
tea_check_pointer
Signature
const void* tea_check_pointer(tea_State* T, int index);Description
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
Example
const void* ctx = tea_check_pointer(T, 1);
See also
tea_check_range
Signature
void tea_check_range(tea_State* T, int index, tea_Number* start, tea_Number* end, tea_Number* step);Description
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
Example
tea_Number start, end, step;
tea_check_range(T, 1, &start, &end, &step);
See also
tea_check_lstring
Signature
const char* tea_check_lstring(tea_State* T, int index, size_t* len);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
Example
size_t len;
const char* data = tea_check_lstring(T, 1, &len);
See also
tea_check_string
Signature
const char* tea_check_string(tea_State* T, int index);Description
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
Example
const char* path = tea_check_string(T, 1);
See also
tea_check_cfunction
Signature
tea_CFunction tea_check_cfunction(tea_State* T, int index);Description
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
Example
tea_CFunction cb = tea_check_cfunction(T, 2);
tea_check_userdata
Signature
void* tea_check_userdata(tea_State* T, int index);Description
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
Example
void* block = tea_check_userdata(T, 1);
See also
tea_check_udata
Signature
void* tea_check_udata(tea_State* T, int idx, const char* name);Description
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
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
Signature
void* tea_test_udata(tea_State* T, int idx, const char* name);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_option
Signature
int tea_check_option(tea_State* T, int index, const char* def, const char* const options[]);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
NULLfor none optionsNULL-terminated array of accepted strings
Returns
The index in options of the selected string.
Errors
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_list
Signature
#define tea_check_list(T, index) tea_check_type(T, (index), TEA_TYPE_LIST)Description
index is a list. Shorthand for tea_check_type with TEA_TYPE_LIST.Parameters
T- Teascript state
index- Stack index of the argument
Errors
Example
tea_check_list(T, 1);
See also
tea_check_map
Signature
#define tea_check_map(T, index) tea_check_type(T, (index), TEA_TYPE_MAP)Description
index is a map. Shorthand for tea_check_type with TEA_TYPE_MAP.Parameters
T- Teascript state
index- Stack index of the argument
Errors
Example
tea_check_map(T, 1);
See also
tea_check_function
Signature
#define tea_check_function(T, index) tea_check_type(T, (index), TEA_TYPE_FUNCTION)Description
index is a function. Shorthand for tea_check_type with TEA_TYPE_FUNCTION.Parameters
T- Teascript state
index- Stack index of the argument
Errors
Example
tea_check_function(T, 1); /* a callback */
See also
tea_check_module
Signature
#define tea_check_module(T, index) tea_check_type(T, (index), TEA_TYPE_MODULE)Description
index is a module. Shorthand for tea_check_type with TEA_TYPE_MODULE.Parameters
T- Teascript state
index- Stack index of the argument
Errors
Example
tea_check_module(T, 1);
See also
tea_check_class
Signature
#define tea_check_class(T, index) tea_check_type(T, (index), TEA_TYPE_CLASS)Description
index is a class. Shorthand for tea_check_type with TEA_TYPE_CLASS.Parameters
T- Teascript state
index- Stack index of the argument
Errors
Example
tea_check_class(T, 1);
See also
tea_check_instance
Signature
#define tea_check_instance(T, index) tea_check_type(T, (index), TEA_TYPE_INSTANCE)Description
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
Example
tea_check_instance(T, 0);