1# Working with String Using Node-API
2
3## Introduction
4
5This topic walks you through on how to use Node-API to convert data between native strings and ArkTS strings.
6
7## Basic Concepts
8
9As a common data type in programming, string is a sequence of characters used to represent text. It can also be used to build user interface (UI) elements such as labels, buttons, and text boxes, process user input, and validate and format input data. Different encodings support different character sets and languages. Major encoding schemes include the following:
10
11- ASCII<br>ASCII is one of the earliest character encoding schemes. It uses 7 bits to represent English letters, digits, and some basic symbols. It serves as the foundation for encoding schemes.
12- UTF-8<br>UTF-8 is a variable-length encoding scheme that can represent any Unicode character. It uses 8 bits per character and uses byte sequences of different lengths depending on the range of the character. UTF-8 is widely used for web content.
13- UTF-16<br>UTF-16 is a fixed-length or variable-length encoding scheme that uses 16 bits per character. It can represent all Unicode characters and is suitable for larger character sets.
14- ISO-8859-1 (Latin-1)<br>ISO-8859-1 is a single-byte coding scheme that uses 8 bits per character. It is mainly used to represent Latin alphabet characters and commonly used in European languages.
15
16## Available APIs
17
18The following table lists the APIs provided by the Node-API module for creating and obtaining strings.
19
20| API| Description|
21| -------- | -------- |
22| napi_get_value_string_utf8 | Obtains a UTF8-encoded string from an ArkTS value.|
23| napi_create_string_utf8 | Creates an ArkTS string from a UTF8-encoded C string.|
24| napi_get_value_string_utf16 | Obtains a UTF16-encoded string from an ArkTS value.|
25| napi_create_string_utf16 | Creates an ArkTS string from a UTF16-encoded C string.|
26| napi_get_value_string_latin1 | Obtains an ISO-8859-1-encoded string from an ArkTS value.|
27| napi_create_string_latin1 | Creates an ArkTS string from an ISO-8859-1-encoded tring.|
28
29## Example
30
31If 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 involved in the string-related APIs.
32
33### napi_get_value_string_utf8
34
35Use **napi_get_value_string_utf8** to convert an ArkTS string to a UTF-8-encoded string.
36
37CPP code:
38
39```cpp
40#include "napi/native_api.h"
41#include <cstring>
42
43static napi_value GetValueStringUtf8(napi_env env, napi_callback_info info)
44{
45    size_t argc = 1;
46    napi_value args[1] = {nullptr};
47
48    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
49    // Obtain the length of the string.
50    size_t length = 0;
51    napi_status status = napi_get_value_string_utf8(env, args[0], nullptr, 0, &length);
52    // napi_string_expected will be returned for non-string inputs.
53    if (status != napi_ok) {
54        return nullptr;
55    }
56    char* buf = new char[length + 1];
57    std::memset(buf, 0, length + 1);
58    napi_get_value_string_utf8(env, args[0], buf, length + 1, &length);
59    napi_value result = nullptr;
60    status = napi_create_string_utf8(env, buf, length, &result);
61    delete buf;
62    if (status != napi_ok) {
63        return nullptr;
64    };
65    return result;
66}
67```
68
69API declaration:
70
71```ts
72// index.d.ts
73export const getValueStringUtf8: (param: string | number) => string | void;
74```
75
76ArkTS code:
77
78```ts
79import hilog from '@ohos.hilog'
80import testNapi from 'libentry.so'
81// Pass in a string and a number respectively. If the input is a string, the string will be returned. If the input is not a string, 'undefined' will be returned.
82hilog.info(0x0000, 'testTag','Test Node-API get_value_string_utf8_string %{public}s', testNapi.getValueStringUtf8 ('aaBC+-$%^Hello 123');
83hilog.info(0x0000, 'testTag', 'Test Node-API get_value_string_utf8_not_string %{public}s', testNapi.getValueStringUtf8(50));
84```
85
86### napi_create_string_utf8
87
88Use **napi_create_string_utf8** to create an ArkTS string from a UTF8-encoded C string.
89
90CPP code:
91
92```cpp
93#include "napi/native_api.h"
94#include <string>
95
96static napi_value CreateStringUtf8(napi_env env, napi_callback_info info)
97{
98    const char *str = u8"Hello, World!, successes to create UTF-8 string! 111";
99    size_t length = strlen(str);
100    napi_value result = nullptr;
101    napi_status status = napi_create_string_utf8(env, str, length, &result);
102    if (status != napi_ok) {
103        napi_throw_error(env, nullptr, "Failed to create UTF-8 string");
104        return nullptr;
105    }
106    return result;
107}
108```
109
110API declaration:
111
112```ts
113// index.d.ts
114export const createStringUtf8: () => string | void;
115```
116
117ArkTS code:
118
119```ts
120import hilog from '@ohos.hilog'
121import testNapi from 'libentry.so'
122
123hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_string_utf8:%{public}s', testNapi.createStringUtf8());
124```
125
126### napi_get_value_string_utf16
127
128Use **napi_get_value_string_utf16** to convert an ArkTS string to a UTF-16-encoded string.
129
130CPP code:
131
132```cpp
133#include "napi/native_api.h"
134
135// Set the maximum length of the string buffer.
136static const int MAX_BUFFER_SIZE = 128;
137
138static napi_value GetValueStringUtf16(napi_env env, napi_callback_info info)
139{
140    size_t argc = 1;
141    napi_value args[1];
142    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
143    napi_value result = nullptr;
144    // Buffer of the string.
145    char16_t buffer[MAX_BUFFER_SIZE];
146    // Size of the buffer for storing the string.
147    size_t bufferSize = MAX_BUFFER_SIZE;
148    // Length of the string.
149    size_t stringLen;
150    // Obtain the value and length of the string.
151    napi_get_value_string_utf16(env, args[0], buffer, bufferSize, &stringLen);
152    // Obtain the string.
153    napi_create_string_utf16(env, buffer, stringLen, &result);
154    // Return the result.
155    return result;
156}
157```
158
159API declaration:
160
161```ts
162// index.d.ts
163export const getValueStringUtf16: (data: string) => string;
164```
165
166ArkTS code:
167
168```ts
169import hilog from '@ohos.hilog'
170import testNapi from 'libentry.so'
171
172let result = testNapi.getValueStringUtf16('hello,');
173hilog.info(0x0000,'testTag','Node-API napi_get_value_string_utf16:%{public}s', result);
174```
175
176### napi_create_string_utf16
177
178Use **napi_create_string_utf16** to create an ArkTS string from a UTF16-encoded C string.
179
180CPP code:
181
182```cpp
183#include "napi/native_api.h"
184
185static napi_value CreateStringUtf16(napi_env env, napi_callback_info info)
186{
187    const char16_t *str = u"Hello, World!, successes to create UTF-16 string! 111";
188    size_t length = NAPI_AUTO_LENGTH;
189    napi_value result = nullptr;
190    napi_status status = napi_create_string_utf16(env, str, length, &result);
191    if (status != napi_ok) {
192        napi_throw_error(env, nullptr, "Failed to create UTF-16 string");
193        return nullptr;
194    }
195    return result;
196}
197```
198
199API declaration:
200
201```ts
202// index.d.ts
203export const createStringUtf16: () => string | void;
204```
205
206ArkTS code:
207
208```ts
209import hilog from '@ohos.hilog'
210import testNapi from 'libentry.so'
211
212hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_string_utf16:%{public}s ', testNapi.createStringUtf16());
213```
214
215### napi_get_value_string_latin1
216
217Use **napi_get_value_string_latin1** to convert an ArkTS string into an ISO-8859-1-encoded string.
218
219CPP code:
220
221```cpp
222#include "napi/native_api.h"
223
224static const int MAX_BUFFER_SIZE = 128;
225
226static napi_value GetValueStringLatin1(napi_env env, napi_callback_info info)
227{
228    size_t argc = 1;
229    napi_value args[1] = {nullptr};
230    napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
231    char buf[MAX_BUFFER_SIZE];
232    size_t length = 0;
233    napi_value napi_Res = nullptr;
234    napi_status status = napi_get_value_string_latin1(env, args[0], buf, MAX_BUFFER_SIZE, &length);
235    // If the value passed in is not a string, napi_string_expected will be returned.
236    if (status == napi_string_expected) {
237        return nullptr;
238    }
239    napi_create_string_latin1(env, buf, length, &napi_Res);
240    return napi_Res;
241}
242```
243
244API declaration:
245
246```ts
247// index.d.ts
248export const getValueStringLatin1: (param: number | string) => string | void;
249```
250
251ArkTS code:
252
253```ts
254import hilog from '@ohos.hilog'
255import testNapi from 'libentry.so'
256// If non-character data is passed in, undefined will be returned.
257hilog.info(0x0000, 'testTag', 'Test Node-API get_value_string_latin1_not_string %{public}s', testNapi.getValueStringLatin1(10));
258// The ISO-8859-1 encoding does not support Chinese characters. If Chinese characters are passed in, garbled characters will be displayed.
259hilog.info(0x0000, 'testTag','Test Node-API get_value_string_latin1_string_chinese %{public}s', testNapi.getValueStringLatin1 ('中文'));
260// Passing in characters of other languages will not cause garbled characters.
261hilog.info(0x0000, 'testTag', 'Test Node-API get_value_string_latin1_string %{public}s', testNapi.getValueStringLatin1('abo ABP=-&*/'));
262```
263
264### napi_create_string_latin1
265
266Use **napi_create_string_latin1** to create an ArkTS string from an ISO-8859-1-encoded C string.
267
268CPP code:
269
270```cpp
271#include "napi/native_api.h"
272
273static napi_value CreateStringLatin1(napi_env env, napi_callback_info info)
274{
275    const char *str = "Hello, World! éçñ, successes to create Latin1 string! 111";
276    size_t length = NAPI_AUTO_LENGTH;
277    napi_value result = nullptr;
278    napi_status status = napi_create_string_latin1(env, str, length, &result);
279    if (status != napi_ok) {
280        // Error handling.
281        napi_throw_error(env, nullptr, "Failed to create Latin1 string");
282        return nullptr;
283    }
284    return result;
285}
286```
287
288API declaration:
289
290```ts
291// index.d.ts
292export const createStringLatin1: () => string | void;
293```
294
295ArkTS code:
296
297```ts
298import hilog from '@ohos.hilog'
299import testNapi from 'libentry.so'
300
301hilog.info(0x0000, 'testTag', 'Test Node-API  napi_create_string_latin1:%{public}s', testNapi.createStringLatin1());
302```
303
304To 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"**.
305
306```text
307// CMakeLists.txt
308add_definitions( "-DLOG_DOMAIN=0xd0d0" )
309add_definitions( "-DLOG_TAG=\"testTag\"" )
310target_link_libraries(entry PUBLIC libhilog_ndk.z.so)
311```
312<!--no_check-->