Added the _restore function to "unpop" the argument stack. (#2592)

Added a unit test for the jerryx_arg_js_iterator_restore function.
Added the specification to the documentation.

JerryScript-DCO-1.0-Signed-off-by: Timothy Harvey t-harvey@ti.com

jerry-ext/arg/arg-js-iterator-helper.c

@@ -30,6 +30,26 @@ jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p) /**< the JS
                                                                   : jerry_create_undefined ());
 } /* jerryx_arg_js_iterator_pop */
 
+/**
+ * Restore the previous JS argument from the iterator.
+ * It will change the index and js_arg_p value in the iterator.
+ *
+ * @return the restored (now current) JS argument.
+ */
+jerry_value_t
+jerryx_arg_js_iterator_restore (jerryx_arg_js_iterator_t *js_arg_iter_p) /**< the JS arg iterator */
+{
+  if (js_arg_iter_p->js_arg_idx == 0)
+  {
+    return jerry_create_undefined ();
+  }
+
+  --js_arg_iter_p->js_arg_idx;
+  --js_arg_iter_p->js_arg_p;
+
+  return *js_arg_iter_p->js_arg_p;
+} /* jerryx_arg_js_iterator_restore */
+
 /**
  * Get the current JS argument from the iterator.
  *

jerry-ext/include/jerryscript-ext/arg.h

@@ -186,6 +186,7 @@ jerryx_arg_transform_optional (jerryx_arg_js_iterator_t *js_arg_iter_p,
 
 /* Helper functions for transform functions. */
 jerry_value_t jerryx_arg_js_iterator_pop (jerryx_arg_js_iterator_t *js_arg_iter_p);
+jerry_value_t jerryx_arg_js_iterator_restore (jerryx_arg_js_iterator_t *js_arg_iter_p);
 jerry_value_t jerryx_arg_js_iterator_peek (jerryx_arg_js_iterator_t *js_arg_iter_p);
 jerry_length_t jerryx_arg_js_iterator_index (jerryx_arg_js_iterator_t *js_arg_iter_p);