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);
[-0, +1, m]

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, tea_add_item, tea_insert_item

tea_new_map

Signature

void tea_new_map(tea_State* T);
[-0, +1, m]

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_list, tea_set_key, tea_set_field

tea_new_class

Signature

void tea_new_class(tea_State* T, const char* name);
[-0, +1, m]

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_create_class, tea_set_methods, tea_new_udata

tea_new_module

Signature

void tea_new_module(tea_State* T, const char* name);
[-0, +1, m]

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_create_module, tea_new_submodule, tea_set_funcs

tea_new_submodule

Signature

void tea_new_submodule(tea_State* T, const char* name);
[-0, +1, m]

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_new_module, tea_create_submodule

tea_create_class

Signature

void tea_create_class(tea_State* T, const char* name, const tea_Methods* klass);
[-0, +1, m]

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
klass
NULL-terminated array of method descriptors; may be NULL for 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_new_class, tea_set_methods, tea_Methods

tea_create_module

Signature

void tea_create_module(tea_State* T, const char* name, const tea_Reg* module);
[-0, +1, m]

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
module
NULL-terminated array of function descriptors; may be NULL for 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);
[-0, +1, m]

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
module
NULL-terminated array of function descriptors; may be NULL for 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_submodule, tea_create_module

tea_new_userdata

Signature

void* tea_new_userdata(tea_State* T, size_t size);
[-0, +1, m]

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, tea_new_udata, tea_set_finalizer

tea_new_userdatav

Signature

void* tea_new_userdatav(tea_State* T, size_t size, int nuvs);
[-0, +1, m]

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_userdata, tea_new_udatav, tea_set_udvalue

tea_new_udata

Signature

void* tea_new_udata(tea_State* T, size_t size, const char* name);
[-0, +1, m]

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, tea_new_userdata, tea_check_udata

tea_new_udatav

Signature

void* tea_new_udatav(tea_State* T, size_t size, int nuvs, const char* name);
[-0, +1, m]

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;

See also

tea_new_userdatav, tea_new_udata, tea_check_udata, tea_create_class

tea_set_udvalue

Signature

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

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 */

See also

tea_get_udvalue, tea_new_userdatav, tea_new_udatav