Update the webpage

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com

3 files changed, 186 insertions, 1 deletions

diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md
index 85c3a2b3..d0811148 100644
--- a/03.API-EXAMPLE.md
+++ b/03.API-EXAMPLE.md
@@ -561,6 +561,50 @@ Value of x is 12
 Value of x is 17
 ```
 
+## Step 8. Changing the seed of pseudorandom generated numbers
+
+If you want to change the seed of `Math.random()` generated numbers, you have to initialize the seed value with `srand`.
+A recommended method is using `jerry_port_get_current_time()` or something based on a constantly changing value, therefore every run produces truly random numbers.
+
+[doctest]: # ()
+
+```c
+#include <string.h>
+#include <stdlib.h>
+#include "jerryscript.h"
+#include "jerryscript-port.h"
+#include "jerryscript-ext/handler.h"
+
+int
+main (void)
+{
+  /* Initialize srand value */
+  srand ((unsigned) jerry_port_get_current_time ());
+
+  /* Generate a random number, and print it */
+  const jerry_char_t script[] = "var a = Math.random (); print(a)";
+  size_t script_size = strlen ((const char *) script);
+
+  /* Initialize the engine */
+  jerry_init (JERRY_INIT_EMPTY);
+
+  /* Register the print function */
+  jerryx_handler_register_global ((const jerry_char_t *) "print",
+                                  jerryx_handler_print);
+
+  /* Evaluate the script */
+  jerry_value_t eval_ret = jerry_eval (script, script_size, false);
+
+  /* Free the JavaScript value returned by eval */
+  jerry_release_value (eval_ret);
+
+  /* Cleanup the engine */
+  jerry_cleanup ();
+
+  return 0;
+}
+```
+
 ## Further steps
 
 For further API description, please visit [API Reference page](https://jerryscript-project.github.io/jerryscript/api-reference/) on [JerryScript home page](https://jerryscript-project.github.io/jerryscript/).
diff --git a/05.PORT-API.md b/05.PORT-API.md
index 3164ddab..80aff025 100644
--- a/05.PORT-API.md
+++ b/05.PORT-API.md
@@ -115,7 +115,7 @@ Allow user to provide external buffer for jerry instance (which includes an isol
  *
  *Note:
  *    This port function will be called automatically by jerry-core
- *    wnen JERRY_ENABLE_EXTERNAL_CONTEXT is defined. If not, this function will never be called.
+ *    when JERRY_ENABLE_EXTERNAL_CONTEXT is defined. If not, this function will never be called.
  *
  * @return the pointer to the jerry instance.
  */
diff --git a/09.EXT-REFERENCE-ARG.md b/09.EXT-REFERENCE-ARG.md
index 16549eda..470607d8 100644
--- a/09.EXT-REFERENCE-ARG.md
+++ b/09.EXT-REFERENCE-ARG.md
@@ -66,6 +66,27 @@ typedef struct
 
 - [jerryx_arg_object_properties](#jerryx_arg_object_properties)
 
+## jerryx_arg_array_items_t
+
+**Summary**
+
+The structure is used in `jerryx_arg_array`. It provides the array items' corresponding 
+JS-to-C mappings and count.
+
+**Prototype**
+
+```c
+typedef struct
+{
+  const jerryx_arg_t *c_arg_p; /**< points to the array of transformation steps */
+  jerry_length_t c_arg_cnt; /**< the count of the `c_arg_p` array */
+} jerryx_arg_array_items_t;
+```
+
+**See also**
+
+- [jerryx_arg_array](#jerryx_arg_array)
+
 ## jerryx_arg_transform_func_t
 
 **Summary**
@@ -320,6 +341,35 @@ jerryx_arg_transform_object_properties (const jerry_value_t obj_val,
 
 - [jerryx_arg_object_properties](#jerryx_arg_object_properties)
 
+## jerryx_arg_transform_array
+
+**Summary**
+
+Validate the JS array and assign its items to the native arguments.
+
+*Note*: This function transforms items of a single JS array into native C values.
+To transform multiple JS arguments in one pass, please use `jerryx_arg_array` together with
+`jerryx_arg_transform_this_and_args` or `jerryx_arg_transform_args`.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerryx_arg_transform_array (const jerry_value_t array_val,
+                            const jerryx_arg_t *c_arg_p,
+                            jerry_length_t c_arg_cnt);
+
+```
+
+ - `array_val` - the JS array.
+ - `c_arg_p` - points to the array of validation/transformation steps
+ - `c_arg_cnt` - the count of the `c_arg_p` array.
+ - return value - a `jerry_value_t` representing `undefined` if all validators passed or an `Error` if a validator failed.
+
+**See also**
+
+- [jerryx_arg_array](#jerryx_arg_array)
+
 
 # Helpers for commonly used validations
 
@@ -590,6 +640,97 @@ my_external_handler (const jerry_value_t function_obj,
 - [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args)
 - [jerryx_arg_transform_object_properties](#jerryx_arg_transform_object_properties)
 
+## jerryx_arg_array
+
+**Summary**
+
+Create a validation/transformation step (`jerryx_arg_t`) that expects to
+consume one `array` JS argument and call `jerryx_arg_transform_array_items` inside
+to transform its items to native arguments.
+User should prepare the `jerryx_arg_array_items_t` instance, and pass it to this function.
+
+**Prototype**
+
+```c
+static inline jerryx_arg_t
+jerryx_arg_array (const jerryx_arg_array_items_t *array_items_p, jerryx_arg_optional_t opt_flag);
+```
+ - return value - the created `jerryx_arg_t` instance.
+ - `array_items_p` - provides items information for transform.
+ - `opt_flag` - whether the argument is optional.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+#include "jerryscript-ext/arg.h"
+
+/**
+ * The binding function expects args_p[0] is an array, which has 3 items:
+ *     first: boolean
+ *     second: number
+ *     third: number, optional
+ */
+static jerry_value_t
+my_external_handler (const jerry_value_t function_obj,
+                     const jerry_value_t this_val,
+                     const jerry_value_t args_p[],
+                     const jerry_length_t args_count)
+{
+  bool required_bool;
+  double required_num;
+  double optional_num = 1234.567;  // default value
+
+  /* "item_mapping" defines the steps to transform array items to C variables. */
+  const jerryx_arg_t item_mapping[] =
+  {
+    jerryx_arg_boolean (&required_bool, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED),
+    jerryx_arg_number (&required_num, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED),
+    jerryx_arg_number (&optional_num, JERRYX_ARG_COERCE, JERRYX_ARG_OPTIONAL)
+  };
+
+  /* Prepare the jerryx_arg_array_items_t instance. */
+  const jerryx_arg_array_items_t array_info =
+  {
+    .c_arg_p = item_mapping,
+    .c_arg_cnt = 3
+  };
+
+  /* It is the mapping used in the jerryx_arg_transform_args. */
+  const jerryx_arg_t mapping[] =
+  {
+    jerryx_arg_array (&array_info, JERRYX_ARG_REQUIRED)
+  };
+
+  /* Validate and transform. */
+  const jerry_value_t rv = jerryx_arg_transform_args (args_p,
+                                                      args_count,
+                                                      mapping,
+                                                      1);
+
+  if (jerry_value_has_error_flag (rv))
+  {
+    /* Handle error. */
+    return rv;
+  }
+
+  /*
+   * Validated and transformed successfully!
+   * required_bool, required_num and optional_num can now be used.
+   */
+
+   return jerry_create_undefined (); /* Or return something more meaningful. */
+}
+
+```
+
+ **See also**
+
+- [jerryx_arg_transform_this_and_args](#jerryx_arg_transform_this_and_args)
+- [jerryx_arg_transform_object_properties](#jerryx_arg_transform_object_properties)
+
 # Functions to create custom validations
 
 ## jerryx_arg_custom