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);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
Signature
void tea_set_fieldi(tea_State* T, int obj, tea_Integer i);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_field
Signature
bool tea_get_field(tea_State* T, int obj);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
Signature
void tea_set_field(tea_State* T, int obj);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_delete_field
Signature
bool tea_delete_field(tea_State* T, int obj);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_get_key
Signature
bool tea_get_key(tea_State* T, int obj, const char* key);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
Signature
void tea_set_key(tea_State* T, int obj, const char* key);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_delete_key
Signature
bool tea_delete_key(tea_State* T, int obj, const char* key);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 */