1# Working with BigInt Using Node-API
2
3## Introduction
4
5BigInt is a data type used to represent integers of any precision in ArkTS, with values greater than the value range of the Number type. You can use Node-API to create, obtain, and operate ArkTS BigInt values.
6
7## Basic Concepts
8
9Before using Node-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 ArkTS. Different from the Number type, BigInt can accurately represent very large integers without losing precision or causing overflows.
12- BigInt creation: You can use Node-API to create a ArkTS BigInt object from a C **Int64** or **Uint64** value. This makes it easy to create BigInt values using C/C++.
13- BigInt operation: Node-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| napi_create_bigint_int64 | Creates an ArkTS BigInt object from a signed 64-bit integer in C/C++.|
20| napi_create_bigint_uint64 | Creates an ArkTS BigInt object from an unsigned 64-bit integer in C/C++.|
21| napi_create_bigint_words | Creates an ArkTS BigInt object from an array of unsigned 64-bit byte data in C/C++.|
22| napi_get_value_bigint_int64 | Obtains a signed 64-bit integer from an ArkTS BigInt object.|
23| napi_get_value_bigint_uint64 | Obtains an unsigned 64-bit integer from an ArkTS BigInt object.|
24| napi_get_value_bigint_words | Obtains the underlying 64-bit unsigned (uint64) byte data from an ArkTS BigInt object.|
25
26
27## Example
28
29If you are just starting out with Node-API, see [Node-API Development Process](use-napi-process.md). The following demonstrates only the C++ and ArkTS code related to BigInt conversions.
30
31### napi_create_bigint_int64
32
33Use **napi_create_bigint_int64** to create an ArkTS BigInt object from a signed 64-bit integer in C/C++.
34
35CPP code:
36
37```cpp
38#include "napi/native_api.h"
39
40static napi_value CreateBigintInt64t(napi_env env, napi_callback_info info)
41{
42    // Declare the int64_t variable value.
43    int64_t value = -5555555555555555555;
44    // Convert the value to the napi_value type and return napi_value.
45    napi_value returnValue = nullptr;
46    napi_create_bigint_int64(env, value, &returnValue);
47    return returnValue;
48}
49```
50
51API declaration:
52
53```ts
54// index.d.ts
55export const createBigintInt64t: () => bigint;
56```
57
58ArkTS code:
59
60```ts
61import hilog from '@ohos.hilog'
62import testNapi from 'libentry.so'
63
64hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_int64: %{public}d', testNapi.createBigintInt64t());
65```
66
67### napi_create_bigint_uint64
68
69Use **napi_create_bigint_uint64** to create an ArkTS BigInt object from an unsigned 64-bit integer in C/C++.
70
71CPP code:
72
73```cpp
74#include "napi/native_api.h"
75
76static napi_value CreateBigintUint64t(napi_env env, napi_callback_info info)
77{
78    // Declare the uint64_t variable value.
79    uint64_t value = 5555555555555555555;
80    // Convert the value to the napi_value type and return napi_value.
81    napi_value returnValue = nullptr;
82    napi_create_bigint_uint64(env, value, &returnValue);
83    return returnValue;
84}
85```
86
87API declaration:
88
89```ts
90// index.d.ts
91export const createBigintUint64t: () => bigint;
92```
93
94ArkTS code:
95
96```ts
97import hilog from '@ohos.hilog'
98import testNapi from 'libentry.so'
99
100hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_uint64: %{public}d', testNapi.createBigintUint64t());
101```
102
103### napi_create_bigint_words
104
105Use **napi_create_bigint_words** to create an ArkTS BigInt object based on the given byte data.
106
107CPP code:
108
109```cpp
110#include "napi/native_api.h"
111
112static napi_value CreateBigintWords(napi_env env, napi_callback_info info)
113{
114    // Call napi_create_bigint_words to create a BigInt object.
115    int signBit = 0;
116    size_t wordCount = 3;
117    uint64_t words[] = {12ULL, 34ULL, 56ULL};
118    napi_value returnValue = nullptr;
119    napi_status status = napi_create_bigint_words(env, signBit, wordCount, words, &returnValue);
120    if (status != napi_ok) {
121        napi_throw_error(env, nullptr, "napi_create_bigint_words fail");
122        return nullptr;
123    }
124    return returnValue;
125}
126```
127
128API declaration:
129
130```ts
131// index.d.ts
132export const createBigintWords: () => bigint | void;
133```
134
135ArkTS code:
136
137```ts
138import hilog from '@ohos.hilog'
139import testNapi from 'libentry.so'
140try {
141  hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_words: %{public}d', testNapi.createBigintWords());
142} catch (error) {
143  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
144}
145```
146
147### napi_get_value_bigint_int64
148
149Use **napi_get_value_bigint_int64** to obtain a signed 64-bit integer from an ArkTS BigInt object.
150
151CPP code:
152
153```cpp
154#include "napi/native_api.h"
155
156static napi_value GetValueBigintInt64t(napi_env env, napi_callback_info info)
157{
158    size_t argc = 1;
159    napi_value args[1] = {nullptr};
160    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
161    // Obtain the 64-bit big integer from the input parameter.
162    int64_t value = 0;
163    bool lossLess = false;
164    napi_status status = napi_get_value_bigint_int64(env, args[0], &value, &lossLess);
165    // Check whether the BigInt value obtained is a product of lossless conversion. If no, throw an exception.
166    if (!lossLess) {
167        napi_throw_error(env, nullptr, "BigInt values have not been lossless converted");
168        return nullptr;
169    }
170    // If the API is successfully called, return true to ArkTS.
171    napi_value returnValue = nullptr;
172    napi_get_boolean(env, status == napi_ok, &returnValue);
173    return returnValue;
174}
175```
176
177API declaration:
178
179```ts
180// index.d.ts
181export const getValueBigintInt64t: (bigInt64: bigint) => boolean | void;
182```
183
184ArkTS code:
185
186```ts
187import hilog from '@ohos.hilog'
188import testNapi from 'libentry.so'
189let bigInt = BigInt(-5555555555555555);
190try {
191  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_int64: %{public}s',
192             JSON.stringify(testNapi.getValueBigintInt64t(bigInt)));
193} catch (error) {
194  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
195}
196```
197
198### napi_get_value_bigint_uint64
199
200Use **napi_get_value_bigint_uint64** to obtain an unsigned 64-bit integer from an ArkTS BigInt object.
201
202CPP code:
203
204```cpp
205#include "napi/native_api.h"
206
207static napi_value GetValueBigintUint64t(napi_env env, napi_callback_info info)
208{
209    size_t argc = 1;
210    napi_value args[1] = {nullptr};
211    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
212    // Obtain the BigInt value.
213    uint64_t value = 0;
214    bool lossLess = false;
215    napi_status status = napi_get_value_bigint_uint64(env, args[0], &value, &lossLess);
216    // Check whether the BigInt value obtained is a product of lossless conversion. If no, throw an exception.
217    if (!lossLess) {
218        napi_throw_error(env, nullptr, "BigInt values have no lossless converted");
219        return nullptr;
220    }
221    // If the API is successfully called, return true to ArkTS.
222    napi_value returnValue = nullptr;
223    napi_get_boolean(env, status == napi_ok, &returnValue);
224    return returnValue;
225}
226```
227
228API declaration:
229
230```ts
231// index.d.ts
232export const getValueBigintUint64t: (bigUint64: bigint) => boolean | void;
233```
234
235ArkTS code:
236
237```ts
238import hilog from '@ohos.hilog'
239import testNapi from 'libentry.so'
240let bigUint = BigInt(5555555555555555);
241try {
242  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_uint64: %{public}s',
243             JSON.stringify(testNapi.getValueBigintUint64t(bigUint)));
244} catch (error) {
245  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
246}
247```
248
249### napi_get_value_bigint_words
250
251Use **napi_get_value_bigint_words** to obtain the underlying unsigned 64-bit (uint64) binary byte data from an ArkTS BigInt object.
252
253CPP code:
254
255```cpp
256#include "hilog/log.h"
257#include "napi/native_api.h"
258
259static napi_value GetValueBigintWords(napi_env env, napi_callback_info info)
260{
261    size_t argc = 1;
262    napi_value args[1] = {nullptr};
263    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
264    int signBit = 0;
265    size_t wordCount = 0;
266    uint64_t words = 0;
267    // Call napi_get_value_bigint_words to obtain wordCount.
268    napi_status status = napi_get_value_bigint_words(env, args[0], nullptr, &wordCount, nullptr);
269    OH_LOG_INFO(LOG_APP, "Node-API , wordCount:%{public}d.", wordCount);
270    // Call napi_get_value_bigint_words to obtain BigInt information, such as whether the value passed by signBit is a positive or negative number.
271    status = napi_get_value_bigint_words(env, args[0], &signBit, &wordCount, &words);
272    OH_LOG_INFO(LOG_APP, "Node-API , signBit: %{public}d.", signBit);
273    if (status != napi_ok) {
274        OH_LOG_ERROR(LOG_APP, "Node-API , reason:%{public}d.", status);
275        napi_throw_error(env, nullptr, "napi_get_date_value fail");
276        return nullptr;
277    }
278    // Convert the sign bit into a value of Int type and pass it.
279    napi_value returnValue = nullptr;
280    napi_create_int32(env, signBit, &returnValue);
281    return returnValue;
282}
283```
284
285API declaration:
286
287```ts
288// index.d.ts
289export const getValueBigintWords: (bigIntWords: bigint) => bigint | void;
290```
291
292ArkTS code:
293
294```ts
295import hilog from '@ohos.hilog'
296import testNapi from 'libentry.so'
297let bigInt = BigInt(-5555555555555555);
298let bigUint = BigInt(5555555555555555);
299try {
300  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_words signBit is: %{public}d', testNapi.getValueBigintWords(bigInt));
301  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_words signBit is: %{public}d', testNapi.getValueBigintWords(bigUint));
302} catch (error) {
303  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
304}
305```
306
307To print logs in the native CPP, add the following information to the **CMakeLists.txt** file and add the header file by using **#include "hilog/log.h"**.
308
309```text
310// CMakeLists.txt
311add_definitions( "-DLOG_DOMAIN=0xd0d0" )
312add_definitions( "-DLOG_TAG=\"testTag\"" )
313target_link_libraries(entry PUBLIC libhilog_ndk.z.so)
314```
315