Create API for handling BigInts (#4111)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2020-08-07 13:43:29 +02:00
parent 082085a8fd
commit cb14682983
8 changed files with 833 additions and 54 deletions
@@ -2031,6 +2031,69 @@ main (void)
 - [jerry_release_value](#jerry_release_value)
 - [jerry_create_symbol](#jerry_create_symbol)

+
+## jerry_value_is_bigint
+
+**Summary**
+
+Returns whether the given `jerry_value_t` is a bigint value.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked
+  in runtime with the `JERRY_FEATURE_BIGINT` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
+
+**Prototype**
+
+```c
+bool
+jerry_value_is_bigint (const jerry_value_t value)
+```
+
+- `value` - API value
+- return value
+  - true, if the given `jerry_value_t` is a BigInt
+  - false, otherwise
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t string_value = jerry_create_string ((const jerry_char_t *) "12345678");
+  jerry_value_t bigint_value = jerry_value_to_bigint (string_value);
+
+  jerry_release_value (string_value);
+
+  if (jerry_value_is_bigint (bigint_value))
+  {
+    // usage of bigint_value
+  }
+
+  jerry_release_value (bigint_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_release_value](#jerry_release_value)
+- [jerry_create_bigint](#jerry_create_bigint)
+- [jerry_value_to_bigint](#jerry_value_to_bigint)
+
+
 ## jerry_value_is_typedarray

 **Summary**
@@ -3374,6 +3437,50 @@ jerry_value_to_string (const jerry_value_t value);
 - [jerry_value_to_primitive](#jerry_value_to_primitive)


+## jerry_value_to_bigint
+
+**Summary**
+
+Call the BigInt constructor ecma builtin operation on the api value.
+
+*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_value_to_bigint (const jerry_value_t value);
+```
+
+- `value` - api value
+- return value
+  - converted BigInt value, if success
+  - thrown error, otherwise
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  jerry_value_t bigint_value = jerry_value_to_bigint (value);
+
+  jerry_release_value (bigint_value);
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_release_value](#jerry_release_value)
+- [jerry_value_is_bigint](#jerry_value_is_bigint)
+- [jerry_get_bigint_digits](#jerry_get_bigint_digits)
+
+
 # Functions for promise objects

 These APIs all depend on the es.next profile (or on some build options).
@@ -3643,6 +3750,133 @@ main (void)
 }
 ```

+# Functions for BigInts
+
+These APIs all depend on build option (`JERRY_BUILTIN_BIGINT`).
+
+## jerry_get_bigint_size_in_digits
+
+**Summary**
+
+Returns the size of uint64 digits of a BigInt value. This value is the
+minimum size of the buffer which can hold all digits of a BigInt value when
+the digits are retreived by `[jerry_get_bigint_digits](#jerry_get_bigint_digits)`.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked
+  in runtime with the `JERRY_FEATURE_BIGINT` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+
+**Prototype**
+
+```c
+uint32_t
+jerry_get_bigint_size_in_digits (jerry_value_t value)
+```
+
+- `value` - BigInt value
+- return value
+  - number of digits (can be zero for BigInt zero)
+  - if value is not a BigInt value, it returns with zero
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  uint64_t digits[4] = { 0x1, 0x1, 0x0, 0x0 };
+  jerry_value_t bigint_value = jerry_create_bigint (digits, 4, true);
+
+  /* Prints two, because the leading zeroes in digits buffer are discarded. */
+  printf("size: %d\n", (int) jerry_get_bigint_size_in_digits (bigint_value));
+
+  jerry_release_value (bigint_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_value_is_bigint](#jerry_value_is_bigint)
+- [jerry_get_bigint_digits](#jerry_get_bigint_digits)
+
+
+## jerry_get_bigint_digits
+
+**Summary**
+
+Copies the uint64 digits of a BigInt value into a buffer. This function supports any
+buffer sizes. If the buffer size is smaller than the size returned by
+`[jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits)`, only the
+least significant digits are copied into the buffer. If the buffer size is greater,
+the unused digits are filled with zero.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked
+  in runtime with the `JERRY_FEATURE_BIGINT` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+
+**Prototype**
+
+```c
+void
+jerry_get_bigint_digits (jerry_value_t value, uint64_t *digits_p, uint32_t size, bool *sign_p)
+```
+
+- `value` - BigInt value
+- `digits_p` - output buffer for digits
+- `size` - size of the output buffer
+- `sign_p` - the boolean passed to the function is set to false when the BigInt
+             is positive, and set to true otherwise (this parameter can be NULL)
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  uint64_t digits[4] = { 0x1, 0x1, 0x0, 0x0 };
+  jerry_value_t bigint_value = jerry_create_bigint (digits, 4, true);
+
+  uint64_t get_digits[4];
+  bool sign;
+  jerry_get_bigint_digits (bigint_value, get_digits, 2, &sign);
+
+  jerry_release_value (bigint_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_value_is_bigint](#jerry_value_is_bigint)
+- [jerry_get_bigint_size_in_digits](#jerry_get_bigint_size_in_digits)
+

 # Acquire and release API values

@@ -4716,6 +4950,65 @@ main (void)
 - [jerry_release_value](#jerry_release_value)


+## jerry_create_bigint
+
+**Summary**
+
+Create BigInt value from uint64 digits
+
+*Note*:
+- This API depends on a build option (`JERRY_BUILTIN_BIGINT`) and can be checked
+  in runtime with the `JERRY_FEATURE_BIGINT` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+  when it is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_bigint (const uint64_t *digits_p, uint32_t size, bool sign)
+```
+
+- `digits_p` - array of uint64 digits, least significant digit first
+- `size` - size of the `digits_p` array
+- `sign` - false if the created value should be positive, and true if the created value should be negative
+- return value
+  - value of the created bigint, if success
+  - thrown error, otherwise
+
+*New in version [[NEXT_RELEASE]]*
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  uint64_t digits[2] = { 0x1, 0x1 };
+  jerry_value_t bigint_value = jerry_create_bigint (digits, 2, true);
+
+  // usage of bigint_value
+
+  jerry_release_value (bigint_value);
+
+  jerry_cleanup ();
+}
+```
+
+**See also**
+
+- [jerry_release_value](#jerry_release_value)
+- [jerry_value_is_bigint](#jerry_value_is_bigint)
+- [jerry_get_bigint_digits](#jerry_get_bigint_digits)
+
+
 ## jerry_create_regexp

 **Summary**