Functions for reading, writing and deleting the fields of a map, by integer key, by string key, or by an arbitrary key taken from the stack. They work on the map directly. To honour operator methods such as [] and []=, use tea_get_index and tea_set_index from the Attribute Access section instead.

The obj index is always evaluated before any value is popped, so -2 still refers to the same slot whether or not the key is popped by the call.

tea_get_fieldi

Signature

bool tea_get_fieldi(tea_State* T, int obj, tea_Integer i);
[-0, +(1|0), -]

Description

Pushes the value stored under the integer key i in the map at obj. Returns true if the key is present. If it is not, returns false and pushes nothing.

Parameters

T
Teascript state
obj
Stack index of the map
i
Integer key to look up

Returns

true if the field exists and was pushed; false otherwise.

Example

tea_new_map(T);                       /* [map] */
tea_push_integer(T, 42);
tea_set_fieldi(T, -2, 0);             /* map[0] = 42 */

bool ok = tea_get_fieldi(T, -1, 0);   /* ok = true, pushes 42 */
tea_pop(T, 1);
ok = tea_get_fieldi(T, -1, 7);        /* ok = false, nothing pushed */

See also

tea_set_fieldi, tea_get_key, tea_get_field

tea_set_fieldi

Signature

void tea_set_fieldi(tea_State* T, int obj, tea_Integer i);
[-1, +0, m]

Description

Pops the value on top of the stack and stores it under the integer key i in the map at obj.

Parameters

T
Teascript state
obj
Stack index of the map
i
Integer key to assign

Errors

May raise a memory error.

Example

tea_new_map(T);                  /* [map] */
tea_push_string(T, "zero");
tea_set_fieldi(T, -2, 0);        /* map[0] = "zero" */
tea_push_integer(T, 100);
tea_set_fieldi(T, -2, 1);        /* map[1] = 100 */

See also

tea_get_fieldi, tea_set_key, tea_set_field

tea_get_field

Signature

bool tea_get_field(tea_State* T, int obj);
[-1, +(1|0), -]

Description

Pops a key from the top of the stack and pushes the value stored under it in the map at obj. Returns true if the key is present. If it is not, returns false and pushes nothing; the key is popped either way.

Parameters

T
Teascript state
obj
Stack index of the map

Returns

true if the field exists and its value was pushed; false otherwise.

Example

tea_new_map(T);                       /* [map] */
tea_push_string(T, "Tea");
tea_set_key(T, -2, "name");           /* map["name"] = "Tea" */

tea_push_string(T, "name");           /* [map, "name"] */
bool ok = tea_get_field(T, -2);       /* ok = true, [map, "Tea"] */

See also

tea_set_field, tea_get_key, tea_get_fieldi

tea_set_field

Signature

void tea_set_field(tea_State* T, int obj);
[-2, +0, m]

Description

Pops a value and a key from the stack and stores the value under that key in the map at obj. The value is on top, with the key just below it.

Parameters

T
Teascript state
obj
Stack index of the map

Errors

May raise a memory error.

Example

tea_new_map(T);                  /* [map] */
tea_push_string(T, "count");
tea_push_integer(T, 7);
tea_set_field(T, -3);            /* map["count"] = 7 */

See also

tea_get_field, tea_set_key, tea_set_fieldi

tea_delete_field

Signature

bool tea_delete_field(tea_State* T, int obj);
[-1, +0, -]

Description

Pops a key from the top of the stack and removes the entry stored under it from the map at obj. Returns true if the key was present and has been removed, false otherwise.

Parameters

T
Teascript state
obj
Stack index of the map

Returns

true if an entry was removed; false otherwise.

Example

tea_new_map(T);
tea_push_integer(T, 1);
tea_set_key(T, -2, "temp");               /* map["temp"] = 1 */

tea_push_string(T, "temp");
bool removed = tea_delete_field(T, -2);   /* removed = true, the map is empty */

See also

tea_set_field, tea_delete_key

tea_get_key

Signature

bool tea_get_key(tea_State* T, int obj, const char* key);
[-0, +(1|0), -]

Description

Pushes the value stored under the string key in the map at obj. Returns true if the key is present. If it is not, returns false and pushes nothing.

Parameters

T
Teascript state
obj
Stack index of the map
key
NUL-terminated string key to look up

Returns

true if the field exists and was pushed; false otherwise.

Example

tea_new_map(T);                             /* [map] */
tea_push_string(T, "1.0");
tea_set_key(T, -2, "version");              /* map["version"] = "1.0" */

bool ok = tea_get_key(T, -1, "version");    /* ok = true, pushes "1.0" */
tea_pop(T, 1);
ok = tea_get_key(T, -1, "missing");         /* ok = false, nothing pushed */

See also

tea_set_key, tea_get_fieldi, tea_get_field

tea_set_key

Signature

void tea_set_key(tea_State* T, int obj, const char* key);
[-1, +0, m]

Description

Pops the value on top of the stack and stores it under the string key in the map at obj. Only the value is popped: the key is given as a C string, not taken from the stack.

Parameters

T
Teascript state
obj
Stack index of the map
key
NUL-terminated string key to assign

Errors

May raise a memory error.

Example

tea_new_map(T);
tea_push_integer(T, 3);
tea_set_key(T, -2, "x");    /* map["x"] = 3 */
tea_push_integer(T, 4);
tea_set_key(T, -2, "y");    /* map["y"] = 4 */

See also

tea_get_key, tea_set_fieldi, tea_set_field

tea_delete_key

Signature

bool tea_delete_key(tea_State* T, int obj, const char* key);
[-0, +0, -]

Description

Removes the entry stored under the string key from the map at obj. Returns true if the key was present and has been removed, false otherwise.

Parameters

T
Teascript state
obj
Stack index of the map
key
NUL-terminated string key to delete

Returns

true if an entry was removed; false otherwise.

Example

tea_new_map(T);
tea_push_integer(T, 5);
tea_set_key(T, -2, "score");                      /* map["score"] = 5 */

bool removed = tea_delete_key(T, -1, "score");    /* removed = true */
removed = tea_delete_key(T, -1, "score");         /* removed = false */

See also

tea_set_key, tea_delete_field