• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Working with BigInt Using JSVM-API
2
3## Introduction
4
5BigInt is a data type used to represent integers of any precision in JavaScript (JS), with values greater than the value range of the Number type. You can use JSVM-API to create, obtain, and operate JS BigInt values.
6
7## Basic Concepts
8
9Before using JSVM-API to operate BigInt values, you need to understand the following basic concepts:
10
11- BigInt: a data type used to represent integers of any precision in JS. Different from the Number type, BigInt can accurately represent very large integers without losing precision or causing overflows.
12- BigInt creation: You can use JSVM-API to create a JS BigInt object from a C **Int64** or **Uint64** value. This makes it easy to create BigInt values using C/C++.
13- BigInt operation: JSVM-API provides APIs for operating BigInt values. You can use these APIs to obtain and convert BigInt values and perform arithmetic and bitwise operations.
14
15## Available APIs
16
17| API                        | Description                                |
18| ---------------------------- | ---------------------------------------- |
19| OH_JSVM_CreateBigintInt64     | Creates a JS BigInt object from a C int64_t object.|
20| OH_JSVM_CreateBigintUint64    | Creates a JS BigInt object from a C uint64_t object.|
21| OH_JSVM_CreateBigintWords     | Creates a JS BigInt object from a C uint64_t array.|
22| OH_JSVM_GetValueBigintInt64  | Obtains the C int64_t primitive equivalent of the given JS BigInt. If necessary, it truncates the value and sets **lossless** to **false**.      |
23| OH_JSVM_GetValueBigintUint64 | Obtains the C uint64_t primitive equivalent of the given JS BigInt. If necessary, it truncates the value and sets **lossless** to **false**.     |
24| OH_JSVM_GetValueBigintWords  | Obtains the underlying data of a given JS BigInt object, that is, the word representation of BigInt data. Both **signBit** and **words** can be set to **NULL**. In this case, only **wordCount** is obtained.|
25
26## Example
27
28If you are just starting out with JSVM-API, see [JSVM-API Development Process](use-jsvm-process.md). The following demonstrates only the C++ and ArkTS code related to BigInt operations.
29
30### OH_JSVM_GetValueBigintWords
31
32Use **OH_JSVM_GetValueBigintWords** to obtain the underlying data of a given JS BigInt object, that is, the word representation of BigInt data.
33
34CPP code:
35
36```cpp
37// hello.cpp
38#include "napi/native_api.h"
39#include "ark_runtime/jsvm.h"
40#include <hilog/log.h>
41// Register the GetValueBigintWords callback.
42static JSVM_CallbackStruct param[] = {
43    {.data = nullptr, .callback = GetValueBigintWords},
44};
45static JSVM_CallbackStruct *method = param;
46// Set a property descriptor named getValueBigintWords and associate it with a callback. This allows the GetValueBigintWords callback to be called from JS.
47static JSVM_PropertyDescriptor descriptor[] = {
48    {"getValueBigintWords", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
49};
50// Define OH_JSVM_GetValueBigintWords.
51static JSVM_Value GetValueBigintWords(JSVM_Env env, JSVM_CallbackInfo info)
52{
53    size_t argc = 1;
54    JSVM_Value args[1] = {nullptr};
55    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
56    int signBit = 0;
57    size_t wordCount = 0;
58    uint64_t words;
59    // Call OH_JSVM_GetValueBigintWords to obtain wordCount.
60    JSVM_Status status = OH_JSVM_GetValueBigintWords(env, args[0], nullptr, &wordCount, nullptr);
61    OH_LOG_INFO(LOG_APP, "OH_JSVM_GetValueBigintWords wordCount:%{public}d.", wordCount);
62    // Call OH_JSVM_GetValueBigintWords to obtain BigInt information, such as whether the value passed by signBit is a positive or negative number.
63    status = OH_JSVM_GetValueBigintWords(env, args[0], &signBit, &wordCount, &words);
64    if (status != JSVM_OK) {
65        OH_LOG_ERROR(LOG_APP, "OH_JSVM_GetValueBigintWords fail, status:%{public}d.", status);
66    } else {
67        OH_LOG_INFO(LOG_APP, "OH_JSVM_GetValueBigintWords signBit: %{public}d.", signBit);
68    }
69    // Convert the sign bit into a value of Int type and pass it.
70    JSVM_Value returnValue = nullptr;
71    OH_JSVM_CreateInt32(env, signBit, &returnValue);
72    return returnValue;
73}
74```
75
76ArkTS code:
77
78```ts
79import hilog from "@ohos.hilog"
80// Import the native APIs.
81import napitest from "libentry.so"
82try {
83  let script: string = `getValueBigintWords(BigInt(5555555555555555))`;
84  let result = napitest.runJsVm(script);
85  hilog.info(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords: %{public}s', result);
86} catch (error) {
87  hilog.error(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords error: %{public}s', error.message);
88}
89try {
90  let script: string = `getValueBigintWords(BigInt(-5555555555555555))`;
91  let result = napitest.runJsVm(script);
92  hilog.info(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords: %{public}s', result);
93} catch (error) {
94  hilog.error(0x0000, 'testJSVM', 'Test JSVM getValueBigintWords error: %{public}s', error.message);
95}
96```
97
98### OH_JSVM_CreateBigintWords
99
100Use **OH_JSVM_GetValueBigintWords** to create a JS BigInt object from a C uint64_t array.
101
102CPP code:
103
104```cpp
105// hello.cpp
106#include "napi/native_api.h"
107#include "ark_runtime/jsvm.h"
108#include <hilog/log.h>
109// Register the CreateBigintWords callback.
110static JSVM_CallbackStruct param[] = {
111    {.data = nullptr, .callback = CreateBigintWords},
112};
113static JSVM_CallbackStruct *method = param;
114// Set a property descriptor named createBigintWords and associate it with a callback. This allows the CreateBigintWords callback to be called from JS.
115static JSVM_PropertyDescriptor descriptor[] = {
116    {"createBigintWords", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
117};
118// Define OH_JSVM_CreateBigintWords.
119static int DIFF_VALUE_THREE = 3;
120static JSVM_Value CreateBigintWords(JSVM_Env env, JSVM_CallbackInfo info)
121{
122    // Call OH_JSVM_CreateBigintWords to create a BigInt object.
123    int signBit = 0;
124    size_t wordCount = DIFF_VALUE_THREE;
125    uint64_t words[] = {12ULL, 34ULL, 56ULL};
126    JSVM_Value returnValue = nullptr;
127    JSVM_Status status = OH_JSVM_CreateBigintWords(env, signBit, wordCount, words, &returnValue);
128    if (status != JSVM_OK) {
129        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CreateBigintWords fail");
130    } else {
131        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CreateBigintWords success");
132    }
133    return returnValue;
134}
135```
136
137ArkTS code:
138
139```ts
140import hilog from "@ohos.hilog"
141// Import the native APIs.
142import napitest from "libentry.so"
143try {
144  let script: string = `createBigintWords()`;
145  let result = napitest.runJsVm(script);
146  hilog.info(0x0000, 'testJSVM', 'Test JSVM createBigintWords: %{public}s', result);
147} catch (error) {
148  hilog.error(0x0000, 'testJSVM', 'Test JSVM createBigintWords error: %{public}s', error.message);
149}
150```
151
152### OH_JSVM_CreateBigintUint64
153
154Use **OH_JSVM_CreateBigintUint64** to create a JS BigInt object from a C Uint64 object.
155
156CPP code:
157
158```cpp
159// hello.cpp
160#include "napi/native_api.h"
161#include "ark_runtime/jsvm.h"
162#include <hilog/log.h>
163// Declare the variable value of uint64_t.
164static uint64_t TEST_VALUE = 5555555555555555555;
165// Define CreateBigintUint64.
166static JSVM_CallbackStruct param[] = {
167    {.data = nullptr, .callback = CreateBigintUint64},
168};
169static JSVM_CallbackStruct *method = param;
170// Set a property descriptor named createBigintUint64 and associate it with a callback. This allows the CreateBigintUint64 callback to be called from JS.
171static JSVM_PropertyDescriptor descriptor[] = {
172    {"createBigintUint64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
173};
174// Define OH_JSVM_CreateBigintUint64.
175static JSVM_Value CreateBigintUint64(JSVM_Env env, JSVM_CallbackInfo info)
176{
177    // Convert value to the JSVM_Value type and return the value.
178    JSVM_Value returnValue = nullptr;
179    JSVM_Status status = OH_JSVM_CreateBigintUint64(env, TEST_VALUE, &returnValue);
180    if (status != JSVM_OK) {
181        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CreateBigintUint64 fail");
182    } else {
183        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CreateBigintUint64 success");
184    }
185    return returnValue;
186}
187```
188
189ArkTS code:
190
191```ts
192import hilog from "@ohos.hilog"
193// Import the native APIs.
194import napitest from "libentry.so"
195try {
196  let script: string = `createBigintUint64()`;
197  let result = napitest.runJsVm(script);
198  hilog.info(0x0000, 'testJSVM', 'Test JSVM createBigintUint64: %{public}s', result);
199} catch (error) {
200  hilog.error(0x0000, 'testJSVM', 'Test JSVM createBigintUint64 error: %{public}s', error.message);
201}
202```
203
204### OH_JSVM_GetValueBigintUint64
205
206Use **OH_JSVM_GetValueBigintUint64** to obtain the C uint64_t primitive equivalent of the given JS BigInt object.
207
208CPP code:
209
210```cpp
211// hello.cpp
212#include "napi/native_api.h"
213#include "ark_runtime/jsvm.h"
214#include <hilog/log.h>
215// Register the GetValueBigintUint64 callback.
216static JSVM_CallbackStruct param[] = {
217    {.data = nullptr, .callback = GetValueBigintUint64},
218};
219static JSVM_CallbackStruct *method = param;
220// Set a property descriptor named getValueBigintUint64 and associate it with a callback. This allows the GetValueBigintUint64 callback to be called from JS.
221static JSVM_PropertyDescriptor descriptor[] = {
222    {"getValueBigintUint64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
223};
224// Define OH_JSVM_GetValueBigintUint64.
225static JSVM_Value GetValueBigintUint64(JSVM_Env env, JSVM_CallbackInfo info)
226{
227    size_t argc = 1;
228    JSVM_Value args[1] = {nullptr};
229    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
230    // Obtain the BigInt value.
231    uint64_t value = 0;
232    bool lossLess = false;
233    OH_JSVM_GetValueBigintUint64(env, args[0], &value, &lossLess);
234    // Check whether the BigInt value obtained is a product of lossless conversion. If no, an exception is thrown.
235    if (!lossLess) {
236        OH_JSVM_ThrowError(env, nullptr, "BigInt values have no lossless converted");
237        return nullptr;
238    } else {
239        OH_LOG_INFO(LOG_APP, "JSVM GetValueBigintUint64 success:%{public}d", lossLess);
240    }
241    JSVM_Value returnValue = nullptr;
242    OH_JSVM_CreateBigintUint64(env, value, &returnValue);
243    return returnValue;
244}
245```
246
247API declaration:
248
249ArkTS code:
250
251```ts
252import hilog from "@ohos.hilog"
253// Import the native APIs.
254import napitest from "libentry.so"
255try {
256  let script: string = `getValueBigintUint64(BigInt(5555555555555555))`;
257  let result = napitest.runJsVm(script);
258  hilog.info(0x0000, 'testJSVM', 'Test JSVM getValueBigintUint64: %{public}s', result);
259} catch (error) {
260  hilog.error(0x0000, 'testJSVM', 'Test JSVM getValueBigintUint64 error: %{public}s', error.message);
261}
262```
263
264### OH_JSVM_CreateBigintInt64
265
266Use **OH_JSVM_CreateBigintInt64** to create a JS BigInt object from a C Int64 object.
267
268CPP code:
269
270```cpp
271// hello.cpp
272#include "napi/native_api.h"
273#include "ark_runtime/jsvm.h"
274#include <hilog/log.h>
275// Declare the variable value of int64_t.
276static int64_t TEST_VALUE_DEMO = -5555555555555555555;
277// Register the CreateBigintInt64 callback.
278static JSVM_CallbackStruct param[] = {
279    {.data = nullptr, .callback = CreateBigintInt64},
280};
281static JSVM_CallbackStruct *method = param;
282// Set a property descriptor named createBigintInt64 and associate it with a callback. This allows the CreateBigintInt64 callback to be called from JS.
283static JSVM_PropertyDescriptor descriptor[] = {
284    {"createBigintInt64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
285};
286// Define OH_JSVM_CreateBigintInt64.
287static JSVM_Value CreateBigintInt64(JSVM_Env env, JSVM_CallbackInfo info)
288{
289    JSVM_Value returnValue = nullptr;
290    JSVM_Status status = OH_JSVM_CreateBigintInt64(env, TEST_VALUE_DEMO, &returnValue);
291    if (status != JSVM_OK) {
292        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_CreateBigintInt64 fail");
293    } else {
294        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_CreateBigintInt64 success");
295    }
296    return returnValue;
297}
298```
299
300ArkTS code:
301
302```ts
303import hilog from "@ohos.hilog"
304// Import the native APIs.
305import napitest from "libentry.so"
306try {
307  let script: string = `createBigintInt64()`;
308  let result = napitest.runJsVm(script);
309  hilog.info(0x0000, 'testJSVM', 'Test JSVM createBigintInt64: %{public}s', result);
310} catch (error) {
311  hilog.error(0x0000, 'testJSVM', 'Test JSVM createBigintInt64 error: %{public}s', error.message);
312}
313```
314
315### OH_JSVM_GetValueBigintInt64
316
317Use OH_JSVM_GetValueBigintInt64 to obtain the C int64_t primitive equivalent of the given JS BigInt object.
318
319CPP code:
320
321```cpp
322// hello.cpp
323#include "napi/native_api.h"
324#include "ark_runtime/jsvm.h"
325#include <hilog/log.h>
326// Register the GetBigintInt64 callback.
327static JSVM_CallbackStruct param[] = {
328    {.data = nullptr, .callback = GetBigintInt64},
329};
330static JSVM_CallbackStruct *method = param;
331// Set a property descriptor named getBigintInt64 and associate it with a callback. This allows the GetBigintInt64 callback to be called from JS.
332static JSVM_PropertyDescriptor descriptor[] = {
333    {"getBigintInt64", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
334};
335// Define OH_JSVM_GetValueBigintInt64.
336static JSVM_Value GetBigintInt64(JSVM_Env env, JSVM_CallbackInfo info)
337{
338    size_t argc = 1;
339    JSVM_Value args[1] = {nullptr};
340    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
341    // Obtain the 64-bit big integer from the input parameter.
342    int64_t value;
343    bool lossLess;
344    OH_JSVM_GetValueBigintInt64(env, args[0], &value, &lossLess);
345    // Check whether the BigInt value obtained is a product of lossless conversion. If no, an exception is thrown.
346    if (!lossLess) {
347        OH_JSVM_ThrowError(env, nullptr, "BigInt values have no lossless converted");
348        return nullptr;
349    } else {
350        OH_LOG_INFO(LOG_APP, "JSVM GetBigintInt64 success:%{public}d", lossLess);
351    }
352    JSVM_Value returnValue = nullptr;
353    OH_JSVM_CreateBigintInt64(env, value, &returnValue);
354    return returnValue;
355}
356```
357
358ArkTS code:
359
360```ts
361import hilog from "@ohos.hilog"
362// Import the native APIs.
363import napitest from "libentry.so"
364try {
365  let script: string = `getBigintInt64(BigInt(-5555555555555555))`;
366  let result = napitest.runJsVm(script);
367  hilog.info(0x0000, 'testJSVM', 'Test JSVM getBigintInt64: %{public}d', result);
368} catch (error) {
369  hilog.error(0x0000, 'testJSVM', 'Test JSVM getBigintInt64 error: %{public}s', error.message);
370}
371```
372