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);Description
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_next
Signature
int tea_next(tea_State* T, int obj);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
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_add_item
Signature
void tea_add_item(tea_State* T, int list);Description
list.Parameters
T- Teascript state
list- Stack index of the list
Errors
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_get_item
Signature
bool tea_get_item(tea_State* T, int list, int index);Description
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
Signature
bool tea_set_item(tea_State* T, int list, int index);Description
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_insert_item
Signature
bool tea_insert_item(tea_State* T, int list, int index);Description
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_delete_item
Signature
bool tea_delete_item(tea_State* T, int list, int index);Description
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"] */