• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用Node-API接口操作bigint类型值
2<!--Kit: NDK-->
3<!--Subsystem: arkcompiler-->
4<!--Owner: @xliu-huanwei; @shilei123; @huanghello-->
5<!--Designer: @shilei123-->
6<!--Tester: @kirl75; @zsw_zhushiwei-->
7<!--Adviser: @fang-jinxu-->
8
9## 简介
10
11BigInt是ArkTS中用于表示任意精度整数的数据类型，它能够处理比Number类型更大范围的整数值。通过Node-API提供的接口，可以在Node-API模块中创建、获取和操作BigInt类型值，从而实现与BigInt相关的功能扩展。
12
13## 基本概念
14
15在使用Node-API接口操作BigInt类型值时，需要理解以下基本概念：
16
17- **BigInt类型：** BigInt是ArkTS中的一种数据类型，用于表示任意精度的整数。与Number类型不同，BigInt类型可以精确表示非常大的整数，而不会丢失精度或溢出。
18- **BigInt创建：** 使用Node-API提供的接口，可以通过传递C的int64或uint64数据来创建对应的ArkTS BigInt。这使得在Node-API模块中可以方便地创建BigInt类型值。
19- **BigInt操作：** Node-API提供了多个接口用于操作BigInt类型值。通过这些接口，可以获取BigInt的数值，进行数值转换，以及执行常见的算术和位运算操作。
20
21## 场景和功能介绍
22
23| 接口 | 描述 |
24| -------- | -------- |
25| napi_create_bigint_int64 | 用于创建64位带符号整数（int64）的BigInt对象的函数。 |
26| napi_create_bigint_uint64 | 用于创建64位无符号整数（uint64）的BigInt对象的函数。 |
27| napi_create_bigint_words | 用于根据提供的64位无符号（uint64）字节数据创建BigInt对象的函数。 |
28| napi_get_value_bigint_int64 | 用于从BigInt对象中获取64位带符号整数（int64）值的函数。 |
29| napi_get_value_bigint_uint64 | 用于从BigInt对象中获取64位无符号整数（uint64）值的函数。 |
30| napi_get_value_bigint_words | 用于从BigInt对象中获取底层的64位无符号（uint64）字节数据。 |
31
32
33## 使用示例
34
35Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。
36
37### napi_create_bigint_int64
38
39这个函数用于在给定的Node-API环境中依据一个带有符号的64位整数创建一个ArkTS的BigInt对象。
40
41cpp部分代码
42
43```cpp
44#include "napi/native_api.h"
45
46static napi_value CreateBigintInt64t(napi_env env, napi_callback_info info)
47{
48    // 声明int64_t的变量value
49    int64_t value = -5555555555555555555;
50    // 将value转化为napi_value类型返回
51    napi_value returnValue = nullptr;
52    napi_create_bigint_int64(env, value, &returnValue);
53    return returnValue;
54}
55```
56<!-- @[napi_create_bigint_int64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/napi_init.cpp) -->
57
58接口声明
59
60```ts
61// index.d.ts
62export const createBigintInt64t: () => bigint;
63```
64<!-- @[napi_create_bigint_int64_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/types/libentry/Index.d.ts) -->
65
66ArkTS侧示例代码
67
68```ts
69import hilog from '@ohos.hilog';
70import testNapi from 'libentry.so';
71
72hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_int64: %{public}d', testNapi.createBigintInt64t());
73```
74<!-- @[ark_napi_create_bigint_int64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/ets/pages/Index.ets) -->
75
76### napi_create_bigint_uint64
77
78这个函数用于在给定的Node-API环境中依据一个无符号的64位整数创建一个ArkTS的BigInt对象。
79
80cpp部分代码
81
82```cpp
83#include "napi/native_api.h"
84
85static napi_value CreateBigintUint64t(napi_env env, napi_callback_info info)
86{
87    // 声明uint64_t的变量value
88    uint64_t value = 5555555555555555555;
89    // 将value转化为napi_value类型返回
90    napi_value returnValue = nullptr;
91    napi_create_bigint_uint64(env, value, &returnValue);
92    return returnValue;
93}
94```
95<!-- @[napi_create_bigint_uint64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/napi_init.cpp) -->
96
97接口声明
98
99```ts
100// index.d.ts
101export const createBigintUint64t: () => bigint;
102```
103<!-- @[napi_create_bigint_uint64_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/types/libentry/Index.d.ts) -->
104
105ArkTS侧示例代码
106
107```ts
108import hilog from '@ohos.hilog';
109import testNapi from 'libentry.so';
110
111hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_uint64: %{public}d', testNapi.createBigintUint64t());
112```
113<!-- @[ark_napi_create_bigint_uint64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/ets/pages/Index.ets) -->
114
115### napi_create_bigint_words
116
117这个函数用于在给定的Node-API环境中由一系列无符号64位整数创建一个ArkTS的BigInt对象。
118
119cpp部分代码
120
121```cpp
122#include "napi/native_api.h"
123
124static napi_value CreateBigintWords(napi_env env, napi_callback_info info)
125{
126    // 使用napi_create_bigint_words接口创建一个BigInt对象
127    int signBit = 0;
128    size_t wordCount = 3;
129    uint64_t words[] = {12ULL, 34ULL, 56ULL};
130    napi_value returnValue = nullptr;
131    napi_status status = napi_create_bigint_words(env, signBit, wordCount, words, &returnValue);
132    if (status != napi_ok) {
133        napi_throw_error(env, nullptr, "napi_create_bigint_words fail");
134        return nullptr;
135    }
136    return returnValue;
137}
138```
139<!-- @[napi_create_bigint_words](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/napi_init.cpp) -->
140
141接口声明
142
143```ts
144// index.d.ts
145export const createBigintWords: () => bigint | undefined;
146```
147<!-- @[napi_create_bigint_words_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/types/libentry/Index.d.ts) -->
148
149ArkTS侧示例代码
150
151```ts
152import hilog from '@ohos.hilog';
153import testNapi from 'libentry.so';
154try {
155  hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_words: %{public}d', testNapi.createBigintWords());
156} catch (error) {
157  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
158}
159```
160<!-- @[ark_napi_create_bigint_words](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/ets/pages/Index.ets) -->
161
162### napi_get_value_bigint_int64
163
164用于从传入的参数中提取64位整数的BigInt数据，以供后续处理。
165
166cpp部分代码
167
168```cpp
169#include "napi/native_api.h"
170
171static napi_value GetValueBigintInt64t(napi_env env, napi_callback_info info)
172{
173    size_t argc = 1;
174    napi_value args[1] = {nullptr};
175    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
176    // 从传入的参数中提取64位整数的BigInt数据
177    int64_t value = 0;
178    bool lossLess = false;
179    napi_status status = napi_get_value_bigint_int64(env, args[0], &value, &lossLess);
180    // 判断从ArkTS侧获取bigint是否为无损转换，如果不是抛出异常
181    if (!lossLess) {
182        napi_throw_error(env, nullptr, "BigInt values have not been lossless converted");
183        return nullptr;
184    }
185    // 如果接口调用成功正常调用则返回true给ArkTS侧
186    napi_value returnValue = nullptr;
187    if (status == napi_ok) {
188      napi_get_boolean(env, true, &returnValue);
189      return returnValue;
190    } else {
191      napi_throw_error(env, nullptr, "napi_get_value_bigint_int64 failed");
192      return nullptr;
193    }
194}
195```
196<!-- @[napi_get_value_bigint_int64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/napi_init.cpp) -->
197
198接口声明
199
200```ts
201// index.d.ts
202export const getValueBigintInt64t: (bigInt64: bigint) => boolean | undefined;
203```
204<!-- @[napi_get_value_bigint_int64_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/types/libentry/Index.d.ts) -->
205
206ArkTS侧示例代码
207
208```ts
209import hilog from '@ohos.hilog';
210import testNapi from 'libentry.so';
211let bigInt = BigInt(-5555555555555555);
212try {
213  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_int64: %{public}s',
214             JSON.stringify(testNapi.getValueBigintInt64t(bigInt)));
215} catch (error) {
216  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
217}
218```
219<!-- @[ark_napi_get_value_bigint_int64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/ets/pages/Index.ets) -->
220
221### napi_get_value_bigint_uint64
222
223用于从传入的参数中提取无符号64位整数的BigInt数据，以供后续处理。
224
225cpp部分代码
226
227```cpp
228#include "napi/native_api.h"
229
230static napi_value GetValueBigintUint64t(napi_env env, napi_callback_info info)
231{
232    size_t argc = 1;
233    napi_value args[1] = {nullptr};
234    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
235    // 从参数值中获取BigInt的数值
236    uint64_t value = 0;
237    bool lossLess = false;
238    napi_status status = napi_get_value_bigint_uint64(env, args[0], &value, &lossLess);
239    // 判断从ArkTS侧获取bigint是否为无损转换，如果不是抛出异常
240    if (!lossLess) {
241        napi_throw_error(env, nullptr, "BigInt values have no lossless converted");
242        return nullptr;
243    }
244    // 如果接口调用成功正常调用则返回true给ArkTS侧
245    napi_value returnValue = nullptr;
246    napi_get_boolean(env, status == napi_ok, &returnValue);
247    return returnValue;
248}
249```
250<!-- @[napi_get_value_bigint_uint64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/napi_init.cpp) -->
251
252接口声明
253
254```ts
255// index.d.ts
256export const getValueBigintUint64t: (bigUint64: bigint) => boolean | undefined;
257```
258<!-- @[napi_get_value_bigint_uint64_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/types/libentry/Index.d.ts) -->
259
260ArkTS侧示例代码
261
262```ts
263import hilog from '@ohos.hilog';
264import testNapi from 'libentry.so';
265let bigUint = BigInt(5555555555555555);
266try {
267  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_uint64: %{public}s',
268             JSON.stringify(testNapi.getValueBigintUint64t(bigUint)));
269} catch (error) {
270  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
271}
272```
273<!-- @[ark_napi_get_value_bigint_uint64](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/ets/pages/Index.ets) -->
274
275### napi_get_value_bigint_words
276
277用于获取ArkTS的BigInt对象底层的64位无符号（uint64）二进制字节数据。
278
279cpp部分代码
280
281```cpp
282#include "hilog/log.h"
283#include "napi/native_api.h"
284
285static napi_value GetValueBigintWords(napi_env env, napi_callback_info info)
286{
287    size_t argc = 1;
288    napi_value args[1] = {nullptr};
289    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
290    int signBit = 0;
291    size_t wordCount = 0;
292    // 调用napi_get_value_bigint_words接口获取wordCount
293    napi_status status = napi_get_value_bigint_words(env, args[0], nullptr, &wordCount, nullptr);
294    OH_LOG_INFO(LOG_APP, "Node-API , wordCount:%{public}d.", wordCount);
295    if (status != napi_ok) {
296        OH_LOG_ERROR(LOG_APP, "Node-API , get wordCount fail, status:%{public}d.", status);
297        napi_throw_error(env, nullptr, "napi_get_value_bigint_words call failed");
298        return nullptr;
299    }
300    if (wordCount == 0) {
301        OH_LOG_ERROR(LOG_APP, "Node-API , wordCount is 0, invalid BigInt or empty value.");
302        napi_throw_error(env, nullptr, "napi_get_value_bigint_words returned wordCount 0");
303        return nullptr;
304    }
305    // 分配足够空间存储所有word
306    uint64_t* words = new uint64_t[wordCount];
307    // 调用napi_get_value_bigint_words接口获取传入bigInt相关信息，如：signBit传入bigInt正负信息
308    status = napi_get_value_bigint_words(env, args[0], &signBit, &wordCount, words);
309    OH_LOG_INFO(LOG_APP, "Node-API , signBit: %{public}d.", signBit);
310    if (status != napi_ok) {
311        OH_LOG_ERROR(LOG_APP, "Node-API , reason:%{public}d.", status);
312        delete[] words;
313        napi_throw_error(env, nullptr, "napi_get_value_bigint_words fail");
314        return nullptr;
315    }
316    // 可在此处处理words数组内容，如日志输出等
317    // ...
318     // 将符号位转化为int类型传出去
319    napi_value returnValue = nullptr;
320    napi_create_int32(env, signBit, &returnValue);
321    delete[] words;
322    return returnValue;
323}
324```
325<!-- @[napi_get_value_bigint_words](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/napi_init.cpp) -->
326
327接口声明
328
329```ts
330// index.d.ts
331export const getValueBigintWords: (bigIntWords: bigint) => bigint | undefined;
332```
333<!-- @[napi_get_value_bigint_words_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/cpp/types/libentry/Index.d.ts) -->
334
335ArkTS侧示例代码
336
337```ts
338import hilog from '@ohos.hilog';
339import testNapi from 'libentry.so';
340let bigInt = BigInt(-5555555555555555);
341let bigUint = BigInt(5555555555555555);
342try {
343  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_words signBit is: %{public}d', testNapi.getValueBigintWords(bigInt));
344  hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_value_bigint_words signBit is: %{public}d', testNapi.getValueBigintWords(bigUint));
345} catch (error) {
346  hilog.error(0x0000, 'testTag', 'Test Node-API NapiGetValueBigint: %{public}s', error.message);
347}
348```
349<!-- @[ark_napi_get_value_bigint_words](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIBigint/entry/src/main/ets/pages/Index.ets) -->
350
351以上代码如果要在native cpp中打印日志，需在CMakeLists.txt文件中添加以下配置信息（并添加头文件：#include "hilog/log.h"）：
352
353```text
354// CMakeLists.txt
355add_definitions( "-DLOG_DOMAIN=0xd0d0" )
356add_definitions( "-DLOG_TAG=\"testTag\"" )
357target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)
358```
359