Operations on lists and other collections: getting the length of an object, iterating over a map, and reading, writing, inserting and deleting list items. List positions are zero-based, so the first item is at position 0.

For reading and writing maps by key, see the Field Access section; for the obj[key] operators that honour operator methods, see the Attribute Access section.

tea_len

Signature

int tea_len(tea_State* T, int index);
[-0, +0, -]

Description

Returns the length of the object at index: the number of bytes of a string, the number of items of a list, the number of key-value pairs of a map, or the size in bytes of a userdata’s data block. For any other type, -1 is returned.

Parameters

T
Teascript state
index
Stack index of the object

Returns

The length of the object, or -1 if its type has no length.

Example

tea_new_list(T, 0);
tea_push_integer(T, 10);
tea_add_item(T, -2);
tea_push_integer(T, 20);
tea_add_item(T, -2);          /* [list(10, 20)] */

int n = tea_len(T, -1);       /* n = 2 */

See also

tea_get_item, tea_add_item, tea_get_lstring

tea_next

Signature

int tea_next(tea_State* T, int obj);
[-1, +(2|0), e]

Description

Iterates over the map at obj. It pops a key from the stack and pushes the next key-value pair of the map, with the value on top. To start the traversal, push nil as the key. When there are no more pairs, nothing is pushed and 0 is returned; the key has been popped.

The order of the pairs is not specified. While traversing, do not call tea_to_string or tea_to_lstring directly on the key, since the conversion would change the value that tea_next needs; and do not add new keys to the map.

Because the stack changes at each step, pass an absolute index for obj.

Parameters

T
Teascript state
obj
Stack index of the map

Returns

1 if a pair was pushed; 0 if the traversal is finished.

Errors

Raises a runtime error if the value at obj is not a map, or if the key is not a valid key of the map.

Example

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

int map = tea_absindex(T, -1);
tea_push_nil(T);                  /* first key */
while(tea_next(T, map))           /* [map, key, value] */
{
    const char* key = tea_get_string(T, -2);
    tea_Integer val = tea_get_integer(T, -1);
    printf("%s = %td\n", key, val);
    tea_pop(T, 1);                /* pop the value, keep the key for the next step */
}
/* the key was popped by the last call: [map] */
tea_pop(T, 1);

See also

tea_set_key, tea_get_key, tea_new_map, tea_len

tea_add_item

Signature

void tea_add_item(tea_State* T, int list);
[-1, +0, m]

Description

Pops the value on top of the stack and appends it to the end of the list at list.

Parameters

T
Teascript state
list
Stack index of the list

Errors

May raise a memory error.

Example

tea_new_list(T, 0);          /* [] */
tea_push_string(T, "a");
tea_add_item(T, -2);         /* ["a"] */
tea_push_string(T, "b");
tea_add_item(T, -2);         /* ["a", "b"] */

See also

tea_insert_item, tea_set_item, tea_new_list

tea_get_item

Signature

bool tea_get_item(tea_State* T, int list, int index);
[-0, +1, -]

Description

Pushes the item at position index (zero-based) of the list at list. Returns true if the item exists and was pushed. If index is out of range, returns false and pushes nothing.

Parameters

T
Teascript state
list
Stack index of the list
index
Zero-based position of the item

Returns

true if the item was pushed; false otherwise.

Example

tea_new_list(T, 0);
tea_push_string(T, "x");
tea_add_item(T, -2);
tea_push_string(T, "y");
tea_add_item(T, -2);                /* ["x", "y"] */

bool ok = tea_get_item(T, -1, 1);   /* ok = true, pushes "y" */
tea_pop(T, 1);
ok = tea_get_item(T, -1, 5);        /* ok = false, nothing pushed */

See also

tea_set_item, tea_len, tea_get_index

tea_set_item

Signature

bool tea_set_item(tea_State* T, int list, int index);
[-1, +0, m]

Description

Pops the value on top of the stack and stores it at position index (zero-based) of the list at list. Returns true on success. If index is out of range, returns false and leaves the stack unchanged, so the value is not popped.

Parameters

T
Teascript state
list
Stack index of the list
index
Zero-based position of the item

Returns

true if the item was set; false otherwise.

Example

tea_new_list(T, 0);
tea_push_string(T, "a");
tea_add_item(T, -2);
tea_push_string(T, "b");
tea_add_item(T, -2);                  /* ["a", "b"] */

tea_push_string(T, "B");
bool ok = tea_set_item(T, -2, 1);     /* ok = true, list is ["a", "B"] */

See also

tea_get_item, tea_insert_item, tea_set_index

tea_insert_item

Signature

bool tea_insert_item(tea_State* T, int list, int index);
[-1, +0, m]

Description

Pops the value on top of the stack and inserts it at position index (zero-based) of the list at list, shifting the items at and after index up by one. Returns true on success; if index is out of range, returns false.

Parameters

T
Teascript state
list
Stack index of the list
index
Zero-based position for the new item

Returns

true if the item was inserted; false otherwise.

Example

tea_new_list(T, 0);
tea_push_string(T, "a");
tea_add_item(T, -2);
tea_push_string(T, "c");
tea_add_item(T, -2);                    /* ["a", "c"] */

tea_push_string(T, "b");
bool ok = tea_insert_item(T, -2, 1);    /* ok = true, list is ["a", "b", "c"] */

See also

tea_add_item, tea_delete_item, tea_set_item

tea_delete_item

Signature

bool tea_delete_item(tea_State* T, int list, int index);
[-0, +0, -]

Description

Removes the item at position index (zero-based) from the list at list, shifting the later items down by one. Returns true on success; if index is out of range, returns false. The stack is not changed.

Parameters

T
Teascript state
list
Stack index of the list
index
Zero-based position of the item to delete

Returns

true if the item was deleted; false otherwise.

Example

tea_new_list(T, 0);
tea_push_string(T, "a");
tea_add_item(T, -2);
tea_push_string(T, "b");
tea_add_item(T, -2);
tea_push_string(T, "c");
tea_add_item(T, -2);                    /* ["a", "b", "c"] */

bool ok = tea_delete_item(T, -1, 1);    /* ok = true, list is ["a", "c"] */

See also

tea_insert_item, tea_add_item, tea_len