Implement container operators API function (#4697)

Basically re-opening and updating #4275 Co-authored-by: bence gabor kis <kisbg@inf.u-szeged.hu> JerryScript-DCO-1.0-Signed-off-by: Bela Toth tbela@inf.u-szeged.hu Co-authored-by: bence gabor kis <kisbg@inf.u-szeged.hu>
2021-07-27 12:25:52 +02:00
parent d69fe41085
commit d99905aca6
6 changed files with 437 additions and 0 deletions
@@ -478,6 +478,18 @@ typedef struct jerry_context_t jerry_context_t;

 *New in version 2.0*.

+## jerry_container_operation_t
+
+Enum that contains the supported container operation types
+  - JERRY_CONTAINER_OP_ADD - Set/WeakSet add operation
+  - JERRY_CONTAINER_OP_GET - Map/WeakMap get operation
+  - JERRY_CONTAINER_OP_SET - Map/WeakMap set operation
+  - JERRY_CONTAINER_OP_HAS - Set/WeakSet/Map/WeakMap has operation
+  - JERRY_CONTAINER_OP_DELETE - Set/WeakSet/Map/WeakMap delete operation
+  - JERRY_CONTAINER_OP_SIZE - Set/WeakSet/Map/WeakMap size operation
+  - JERRY_CONTAINER_OP_CLEAR - Set/Map clear operation
+
+*New in version [[NEXT_RELEASE]]*.

 ## jerry_binary_operation_t

@@ -12429,3 +12441,78 @@ main (void)

 - [jerry_create_container](#jerry_create_container)
 - [jerry_container_type_t](#jerry_container_type_t)
+
+
+## jerry_container_operation
+
+**Summary**
+
+Perform container operation on the given operands (add, delete, set, etc.).
+
+*Note*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API function depends on a build option (`JERRY_BUILTIN_CONTAINER`) and can be checked
+  runtime with the `JERRY_FEATURE_MAP` , `JERRY_FEATURE_SET` , `JERRY_FEATURE_WEAKMAP` , `JERRY_FEATURE_WEAKSET`
+  feature enum values.
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_container_operation (jerry_container_operation_t operation,
+                           jerry_value_t container,
+                           jerry_value_t *arguments,
+                           uint32_t arguments_number)
+```
+
+ - `operation` - container operation
+ - `container` - this value
+ - `arguments` - array of arguments
+ - `arguments_number` - number of arguments
+ - result if the operation is successful
+ - error, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t map = jerry_create_container (JERRY_CONTAINER_TYPE_MAP, NULL, 0);
+  jerry_value_t key_str = jerry_create_string ((jerry_char_t *) "number");
+  jerry_value_t number = jerry_create_number (10);
+  jerry_value_t args[2] = {key_str, number};
+
+  jerry_value_t result = jerry_container_operation (JERRY_CONTAINER_OP_SET, map, args, 2);
+  jerry_release_value (result);
+
+  result = jerry_container_operation (JERRY_CONTAINER_OP_SIZE, map, NULL, 0);
+  jerry_release_value (result);
+
+  result = jerry_container_operation (JERRY_CONTAINER_OP_CLEAR, map, NULL, 0);
+  jerry_release_value (result);
+
+  jerry_release_value (map);
+  jerry_release_value (key_str);
+  jerry_release_value (number);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_create_container](#jerry_create_container)
+- [jerry_container_type_t](#jerry_container_type_t)