Functions that create new objects and push them onto the stack: lists, maps, classes, modules and userdata. The
tea_create_* variants also fill in the new class or module from a registration array in one call. Creating an object allocates memory, so every function here can raise a memory error.tea_new_list
Signature
void tea_new_list(tea_State* T, size_t n);Description
Creates a new, empty list and pushes it onto the stack.
n is the capacity to prepare, a hint that avoids reallocations during later tea_add_item calls; it does not set the list’s length.Parameters
T- Teascript state
n- Initial capacity hint
Example
tea_new_list(T, 4); /* [] with room for 4 items */
for(int i = 0; i < 3; i++)
{
tea_push_integer(T, i * 10);
tea_add_item(T, -2);
}
/* the list is now [0, 10, 20] */
See also
tea_new_map
Signature
void tea_new_map(tea_State* T);Description
Creates a new, empty map and pushes it onto the stack.
Parameters
T- Teascript state
Example
tea_new_map(T); /* {} */
tea_push_string(T, "hello");
tea_set_key(T, -2, "greeting"); /* {greeting = "hello"} */
See also
tea_new_class
Signature
void tea_new_class(tea_State* T, const char* name);Description
Creates a new, empty class called
name and pushes it onto the stack. Add methods with tea_set_methods or one at a time with tea_set_attr.Parameters
T- Teascript state
name- Name of the class
Example
tea_new_class(T, "Point");
tea_push_cfunction(T, point_new, 2, 0);
tea_set_attr(T, -2, "new");
See also
tea_new_module
Signature
void tea_new_module(tea_State* T, const char* name);Description
Creates a new, empty module called
name and pushes it onto the stack. The module’s path is set to its name. Add members with tea_set_attr or tea_set_funcs.Parameters
T- Teascript state
name- Name of the module
Example
tea_new_module(T, "mathx");
tea_push_cfunction(T, mathx_sqrt, 1, 0);
tea_set_attr(T, -2, "sqrt");
See also
tea_new_submodule
Signature
void tea_new_submodule(tea_State* T, const char* name);Description
Creates a new, empty submodule called
name and pushes it onto the stack. A submodule is a module meant to be nested inside another module: assign it to the parent with tea_set_attr.Parameters
T- Teascript state
name- Name of the submodule
Example
tea_new_submodule(T, "path");
tea_push_cfunction(T, path_join, TEA_VARG, 0);
tea_set_attr(T, -2, "join");
See also
tea_create_class
Signature
void tea_create_class(tea_State* T, const char* name, const tea_Methods* klass);Description
Creates a new class called
name, registers every method described by the tea_Methods array klass, and pushes the class onto the stack. Each entry gives a method name, its type ("method", "static", "getter" or "setter"), the C function and the argument counts. The array ends with an entry whose name is NULL.Parameters
T- Teascript state
name- Name of the class
klassNULL-terminated array of method descriptors; may beNULLfor an empty class
Example
static const tea_Methods point_methods[] =
{
{"new", "method", point_new, 2, 0},
{"length", "method", point_length, 0, 0},
{"x", "getter", point_getx, 0, 0},
{NULL, NULL, NULL, 0, 0}
};
tea_create_class(T, "Point", point_methods);
tea_set_global(T, "Point");
See also
tea_create_module
Signature
void tea_create_module(tea_State* T, const char* name, const tea_Reg* module);Description
Creates a new module called
name, fills it with the functions described by the tea_Reg array module, and pushes it onto the stack. Each entry gives a name, a C function and the argument counts. An entry with a NULL function stores nil under its name, which is useful as a placeholder to fill in afterwards. The array ends with an entry whose name is NULL.Parameters
T- Teascript state
name- Name of the module
moduleNULL-terminated array of function descriptors; may beNULLfor an empty module
Example
static const tea_Reg mathx_lib[] =
{
{"sqrt", mathx_sqrt, 1, 0},
{"pi", NULL, 0, 0}, /* placeholder */
{NULL, NULL, 0, 0}
};
tea_create_module(T, "mathx", mathx_lib);
tea_push_number(T, 3.14159);
tea_set_attr(T, -2, "pi"); /* fill in the placeholder */
tea_set_global(T, "mathx");
See also
tea_new_module, tea_create_submodule, tea_set_funcs, tea_Reg
tea_create_submodule
Signature
void tea_create_submodule(tea_State* T, const char* name, const tea_Reg* module);Description
Like
tea_create_module, but creates a submodule meant to be nested inside another module. Assign it to the parent with tea_set_attr.Parameters
T- Teascript state
name- Name of the submodule
moduleNULL-terminated array of function descriptors; may beNULLfor an empty submodule
Example
static const tea_Reg path_lib[] =
{
{"join", path_join, TEA_VARG, 0},
{"split", path_split, 1, 0},
{NULL, NULL, 0, 0}
};
tea_create_submodule(T, "path", path_lib); /* [path] */
tea_get_global(T, "os"); /* [path, os] */
tea_insert(T, -2); /* [os, path] */
tea_set_attr(T, -2, "path"); /* os.path = path; [os] */
tea_pop(T, 1);
See also
tea_new_userdata
Signature
void* tea_new_userdata(tea_State* T, size_t size);Description
Creates a new anonymous userdata with a data block of size bytes and no user values, and pushes it onto the stack. Equivalent to tea_new_userdatav(T, size, 0).
The block is managed by the garbage collector. Use tea_set_finalizer to release any native resources it refers to.
Parameters
T- Teascript state
size- Size of the data block in bytes
Returns
A pointer to the data block, valid for as long as the userdata is alive.
Example
void* buf = tea_new_userdata(T, 256);
memset(buf, 0, 256);
See also
tea_new_userdatav
Signature
void* tea_new_userdatav(tea_State* T, size_t size, int nuvs);Description
Creates a new anonymous userdata with a data block of
size bytes and nuvs user values, all initially nil, and pushes it onto the stack. The user values hold Teascript values that live and die with the userdata; access them with tea_get_udvalue and tea_set_udvalue. Unlike tea_new_udatav, the userdata has no class.Parameters
T- Teascript state
size- Size of the data block in bytes
nuvs- Number of user values
Returns
A pointer to the data block, valid for as long as the userdata is alive.
Example
/* a userdata holding one int and one user value */
int* p = (int*)tea_new_userdatav(T, sizeof(int), 1);
*p = 42;
See also
tea_new_udata
Signature
void* tea_new_udata(tea_State* T, size_t size, const char* name);Description
Creates a new userdata with a data block of
size bytes and no user values, associated with the class registered under name, and pushes it onto the stack. Equivalent to tea_new_udatav(T, size, 0, name). The class association is what lets tea_check_udata and tea_test_udata verify the type later.Parameters
T- Teascript state
size- Size of the data block in bytes
name- Name of the registered class to associate
Returns
A pointer to the data block, valid for as long as the userdata is alive.
Example
FILE** f = (FILE**)tea_new_udata(T, sizeof(FILE*), "File");
*f = fopen("data.txt", "r");
See also
tea_new_udatav
Signature
void* tea_new_udatav(tea_State* T, size_t size, int nuvs, const char* name);Description
Creates a new userdata with a data block of
size bytes and nuvs user values, associated with the class registered under name (typically created with tea_new_class or tea_create_class), and pushes it onto the stack. The class association enables type checking with tea_check_udata and tea_test_udata.Parameters
T- Teascript state
size- Size of the data block in bytes
nuvs- Number of user values
name- Name of the registered class to associate
Returns
A pointer to the data block, valid for as long as the userdata is alive.
Example
/* a "RingBuffer" userdata with two user values */
RingBuffer* rb = (RingBuffer*)tea_new_udatav(T, sizeof(RingBuffer), 2, "RingBuffer");
rb->capacity = 16;
tea_set_udvalue
Signature
void tea_set_udvalue(tea_State* T, int ud, int n);Description
Pops the value on top of the stack and stores it as the
n-th user value of the userdata at ud. The userdata must have been created with at least n + 1 user values (see tea_new_userdatav).Parameters
T- Teascript state
ud- Stack index of the userdata
n- Zero-based number of the user value
Example
tea_new_userdatav(T, sizeof(int), 2); /* [ud] */
tea_push_string(T, "tag");
tea_set_udvalue(T, -2, 0); /* user value 0 = "tag" */
tea_push_integer(T, 7);
tea_set_udvalue(T, -2, 1); /* user value 1 = 7 */