js-apis-plainarray.md 20.0 KB
Newer Older
L
linhaoran 已提交
1 2 3 4 5
# 非线性容器PlainArray  

> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:**
> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

6 7 8 9 10 11 12
PlainArray可用于存储具有关联关系的key-value键值对集合,存储元素中key值唯一,key值类型为number类型,每个key对应一个value。

PlainArray依据泛型定义,采用轻量级结构,集合中key值的查找依赖于二分查找算法,然后映射到其他数组中的value值。

PlainArray和[LightWeightMap](js-apis-lightweightmap.md)都是用来存储键值对,且均采用轻量级结构,但PlainArray的key值类型只能为number类型。

**推荐使用场景:** 当需要存储key值为number类型的键值对时,可以使用PlainArray。
L
linhaoran 已提交
13

L
lengchangjing 已提交
14 15 16
文档中存在泛型的使用,涉及以下泛型标记符:<br>
- T: Type, 类

L
linhaoran 已提交
17 18
## 导入模块

19
```ts
20
import PlainArray from '@ohos.util.PlainArray';  
L
linhaoran 已提交
21 22 23 24 25 26 27 28
```



## PlainArray

### 属性

Z
zengyawen 已提交
29 30
**系统能力:** SystemCapability.Utils.Lang

L
linhaoran 已提交
31 32
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
Z
zengyawen 已提交
33
| length | number | 是 | 否 | PlainArray的元素个数。 |
L
linhaoran 已提交
34 35 36 37


### constructor

Z
zengyawen 已提交
38
constructor()
L
linhaoran 已提交
39 40 41

PlainArray的构造函数。

Z
zengyawen 已提交
42 43
**系统能力:** SystemCapability.Utils.Lang

L
liu-ganlin 已提交
44 45 46 47 48 49 50 51
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200012 | The PlainArray's constructor cannot be directly invoked. |

Z
zengyawen 已提交
52 53
**示例:**

54
```ts
Z
zengyawen 已提交
55
let plainArray = new PlainArray();
L
liu-ganlin 已提交
56 57 58 59 60
try {
  let plainArray2 = PlainArray();
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
61
```
L
linhaoran 已提交
62 63 64 65


### isEmpty

Z
zengyawen 已提交
66
isEmpty(): boolean
L
linhaoran 已提交
67 68 69

判断该容器是否为空。

Z
zengyawen 已提交
70 71
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
72 73 74 75 76
**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| boolean | 为空返回true, 不为空返回false。 |
L
linhaoran 已提交
77

L
liu-ganlin 已提交
78 79 80 81 82 83 84 85
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The isEmpty method cannot be bound. |

Z
zengyawen 已提交
86 87
**示例:**

88
```ts
Z
zengyawen 已提交
89
const plainArray = new PlainArray();
90
let result = plainArray.isEmpty();
L
liu-ganlin 已提交
91
try {
L
liu-ganlin 已提交
92
  plainArray.isEmpty.bind({})(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
93 94 95
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
96
```
L
linhaoran 已提交
97 98 99 100


### has

Z
zengyawen 已提交
101
has(key: number): boolean
L
linhaoran 已提交
102 103 104

判断此容器中是否含有该指定key。

Z
zengyawen 已提交
105 106
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
107 108 109 110
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
111
| key | number | 是 | 指定key。 |
Z
zengyawen 已提交
112 113

**返回值:**
L
linhaoran 已提交
114

Z
zengyawen 已提交
115 116
| 类型 | 说明 |
| -------- | -------- |
117
| boolean | 包含指定key返回true,否则返回false。 |
L
linhaoran 已提交
118

L
liu-ganlin 已提交
119 120 121 122 123 124 125 126
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The has method cannot be bound. |

Z
zengyawen 已提交
127 128
**示例:**

129
```ts
Z
zengyawen 已提交
130 131
let plainArray = new PlainArray();
plainArray.has(1);
L
lengchangjing 已提交
132
plainArray.add(1, "squirrel");
133
let result1 = plainArray.has(1);
L
liu-ganlin 已提交
134
try {
L
liu-ganlin 已提交
135
  plainArray.has.bind({}, 1)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
136 137 138
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
139
```
L
linhaoran 已提交
140 141 142 143


### get

Z
zengyawen 已提交
144
get(key: number): T
L
linhaoran 已提交
145 146 147

获取指定key所对应的value。

Z
zengyawen 已提交
148 149
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
150 151 152 153 154 155 156
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| key | number | 是 | 查找的指定key。 |

**返回值:**
L
linhaoran 已提交
157

Z
zengyawen 已提交
158 159 160
| 类型 | 说明 |
| -------- | -------- |
| T | 返回key映射的value值。 |
L
linhaoran 已提交
161

L
liu-ganlin 已提交
162 163 164 165 166 167 168 169
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The get method cannot be bound. |

Z
zengyawen 已提交
170 171
**示例:**

172
```ts
Z
zengyawen 已提交
173
let plainArray = new PlainArray();
L
lengchangjing 已提交
174 175
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
176
let result = plainArray.get(1);
L
liu-ganlin 已提交
177
try {
L
liu-ganlin 已提交
178
  plainArray.get.bind({}, 1)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
179 180 181
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
182
```
L
linhaoran 已提交
183 184 185 186


### getIndexOfKey

187
getIndexOfKey(key: number): number
L
linhaoran 已提交
188

189
查找指定key第一次出现的下标值,如果没有找到该key返回-1。
Z
zengyawen 已提交
190

Z
zengyawen 已提交
191 192
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
193 194 195 196
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
197
| key | number | 是 | 指定key。 |
L
linhaoran 已提交
198

Z
zengyawen 已提交
199
**返回值:**
L
linhaoran 已提交
200

Z
zengyawen 已提交
201 202
| 类型 | 说明 |
| -------- | -------- |
203
| number | 返回指定key第一次出现时的下标值,查找失败返回-1。 |
L
linhaoran 已提交
204

L
liu-ganlin 已提交
205 206 207 208 209 210 211 212
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The getIndexOfKey method cannot be bound. |

Z
zengyawen 已提交
213 214
**示例:**

215
```ts
Z
zengyawen 已提交
216
let plainArray = new PlainArray();
L
lengchangjing 已提交
217 218
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
219
let result = plainArray.getIndexOfKey(2);
L
liu-ganlin 已提交
220
try {
L
liu-ganlin 已提交
221
  plainArray.getIndexOfKey.bind({}, 2)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
222 223 224
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
225
```
L
linhaoran 已提交
226 227 228 229


### getIndexOfValue

230
getIndexOfValue(value: T): number
L
linhaoran 已提交
231

232
查找指定value元素第一次出现的下标值,如果没有找到该value元素返回-1。
Z
zengyawen 已提交
233

Z
zengyawen 已提交
234 235
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
236 237 238 239
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
240
| value | T | 是 | 指定value元素。 |
L
linhaoran 已提交
241

Z
zengyawen 已提交
242
**返回值:**
L
linhaoran 已提交
243

Z
zengyawen 已提交
244 245
| 类型 | 说明 |
| -------- | -------- |
246
| number | 返回指定value元素第一次出现时的下标值,查找失败返回-1。 |
L
linhaoran 已提交
247

L
liu-ganlin 已提交
248 249 250 251 252 253 254 255
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The getIndexOfValue method cannot be bound. |

Z
zengyawen 已提交
256 257
**示例:**

258
```ts
Z
zengyawen 已提交
259
let plainArray = new PlainArray();
L
lengchangjing 已提交
260 261 262
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
let result = plainArray.getIndexOfValue("squirrel");
L
liu-ganlin 已提交
263
try {
L
liu-ganlin 已提交
264
  plainArray.getIndexOfValue.bind({}, "squirrel")(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
265 266 267
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
268
```
L
linhaoran 已提交
269 270 271 272


### getKeyAt

273
getKeyAt(index: number): number
L
linhaoran 已提交
274

Z
zengyawen 已提交
275 276
查找指定下标的元素键值对中key值。

Z
zengyawen 已提交
277 278
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
279 280 281 282
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
283
| index | number | 是 | 指定下标。 |
L
linhaoran 已提交
284

Z
zengyawen 已提交
285
**返回值:**
L
linhaoran 已提交
286

Z
zengyawen 已提交
287 288
| 类型 | 说明 |
| -------- | -------- |
289
| number | 返回该下标对应的元素键值对中key值,失败返回-1。 |
L
linhaoran 已提交
290

L
liu-ganlin 已提交
291 292 293 294 295 296 297 298
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The getKeyAt method cannot be bound. |

Z
zengyawen 已提交
299 300
**示例:**

301
```ts
Z
zengyawen 已提交
302
let plainArray = new PlainArray();
L
lengchangjing 已提交
303 304
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
305
let result = plainArray.getKeyAt(1);
L
liu-ganlin 已提交
306
try {
L
liu-ganlin 已提交
307
  plainArray.getKeyAt.bind({}, 1)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
308 309 310
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
311
```
L
linhaoran 已提交
312

313 314 315 316 317 318
### getValueAt

getValueAt(index: number): T

查找指定下标元素键值对中Value值,否则返回undefined。

Z
zengyawen 已提交
319 320
**系统能力:** SystemCapability.Utils.Lang

321 322 323 324 325 326 327 328 329 330 331 332
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | index | number | 是 | 指定下标。 |

**返回值:**

  | 类型 | 说明 |
  | -------- | -------- |
  | T | 返回该下标对应的元素键值对中key值,失败返回undefined。 |

L
liu-ganlin 已提交
333 334 335 336 337 338 339 340 341
  **错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The getValueAt method cannot be bound. |
| 10200001 | The value of parameters are out of range. |

342 343
**示例:**

L
liu-ganlin 已提交
344 345 346 347 348 349
```ts
let plainArray = new PlainArray();
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
let result = plainArray.getValueAt(1);
try {
L
liu-ganlin 已提交
350
  plainArray.getValueAt.bind({}, 1)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
351 352 353 354 355 356 357 358 359
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
try {
  plainArray.getValueAt(10);
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
```
L
linhaoran 已提交
360 361 362

### clone

Z
zengyawen 已提交
363 364
clone(): PlainArray&lt;T&gt;

365
克隆一个实例,并返回克隆后的实例。修改克隆后的实例并不会影响原实例。
L
linhaoran 已提交
366

Z
zengyawen 已提交
367 368
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
369
**返回值:**
L
linhaoran 已提交
370

Z
zengyawen 已提交
371 372 373
| 类型 | 说明 |
| -------- | -------- |
| PlainArray&lt;T&gt; | 返回新的对象实例。 |
L
linhaoran 已提交
374

L
liu-ganlin 已提交
375 376 377 378 379 380 381 382
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The clone method cannot be bound. |

Z
zengyawen 已提交
383 384
**示例:**

385
```ts
386
let plainArray = new PlainArray();
L
lengchangjing 已提交
387 388
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
Z
zengyawen 已提交
389
let newPlainArray = plainArray.clone();
L
liu-ganlin 已提交
390
try {
L
liu-ganlin 已提交
391
  plainArray.clone.bind({})(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
392 393 394
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
395
```
L
linhaoran 已提交
396 397 398 399


### add

400
add(key: number, value: T): void
L
linhaoran 已提交
401 402 403

向容器中添加一组数据。

Z
zengyawen 已提交
404 405
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
406 407 408 409 410 411 412
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| key | number | 是 | 添加成员数据的键名。 |
| value | T | 是 | 添加成员数据的值。 |

L
liu-ganlin 已提交
413 414 415 416 417 418 419 420
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The add method cannot be bound. |

Z
zengyawen 已提交
421 422
**示例:**

423
```ts
Z
zengyawen 已提交
424
let plainArray = new PlainArray();
L
lengchangjing 已提交
425
plainArray.add(1, "squirrel");
L
liu-ganlin 已提交
426
try {
L
liu-ganlin 已提交
427
  plainArray.add.bind({}, "squirrel")(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
428 429 430
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
431
```
L
linhaoran 已提交
432 433 434 435


### remove

Z
zengyawen 已提交
436
remove(key: number): T
L
linhaoran 已提交
437

438
删除指定key对应元素。
L
linhaoran 已提交
439

Z
zengyawen 已提交
440 441
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
442 443 444 445
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
446
| key | number | 是 | 指定key。 |
Z
zengyawen 已提交
447 448

**返回值:**
L
linhaoran 已提交
449

Z
zengyawen 已提交
450 451 452
| 类型 | 说明 |
| -------- | -------- |
| T | 返回删除元素的值。 |
L
linhaoran 已提交
453

L
liu-ganlin 已提交
454 455 456 457 458 459 460 461
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The remove method cannot be bound. |

Z
zengyawen 已提交
462 463
**示例:**

464
```ts
Z
zengyawen 已提交
465
let plainArray = new PlainArray();
L
lengchangjing 已提交
466 467
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
468
let result = plainArray.remove(2);
L
liu-ganlin 已提交
469
try {
L
liu-ganlin 已提交
470
  plainArray.remove.bind({}, 2)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
471 472 473
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
474
```
L
linhaoran 已提交
475 476 477 478


### removeAt

479
removeAt(index: number): T
L
linhaoran 已提交
480

481
删除指定下标对应的元素。
L
linhaoran 已提交
482

Z
zengyawen 已提交
483 484
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
485 486 487 488 489 490 491
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定元素下标。 |

**返回值:**
L
linhaoran 已提交
492

Z
zengyawen 已提交
493 494
| 类型 | 说明 |
| -------- | -------- |
495
| T | 返回删除的元素。 |
L
linhaoran 已提交
496

L
liu-ganlin 已提交
497 498 499 500 501 502 503 504
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The removeAt method cannot be bound. |

Z
zengyawen 已提交
505 506
**示例:**

507
```ts
Z
zengyawen 已提交
508
let plainArray = new PlainArray();
L
lengchangjing 已提交
509 510
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
511
let result = plainArray.removeAt(1);
L
liu-ganlin 已提交
512
try {
L
liu-ganlin 已提交
513
  plainArray.removeAt.bind({}, 1)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
514 515 516
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
517
```
L
linhaoran 已提交
518 519 520 521


### removeRangeFrom

Z
zengyawen 已提交
522
removeRangeFrom(index: number, size: number): number
L
linhaoran 已提交
523 524 525

删除一定范围内的元素。

Z
zengyawen 已提交
526 527
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
528 529 530 531 532 533 534 535
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 删除元素的起始下标。 |
| size | number | 是 | 期望删除元素个数。 |

**返回值:**
L
linhaoran 已提交
536

Z
zengyawen 已提交
537 538 539
| 类型 | 说明 |
| -------- | -------- |
| number | 实际删除元素个数。 |
L
linhaoran 已提交
540

L
liu-ganlin 已提交
541 542 543 544 545 546 547 548 549
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The removeRangeFrom method cannot be bound. |
| 10200001 | The value of parameters are out of range. |

Z
zengyawen 已提交
550 551
**示例:**

552
```ts
Z
zengyawen 已提交
553
let plainArray = new PlainArray();
L
lengchangjing 已提交
554 555
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
556
let result = plainArray.removeRangeFrom(1, 3);
L
liu-ganlin 已提交
557
try {
L
liu-ganlin 已提交
558
  plainArray.removeRangeFrom.bind({}, 1, 3)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
559 560 561 562 563 564 565 566
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
try {
  plainArray.removeRangeFrom(10, 3);
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
567
```
L
linhaoran 已提交
568 569 570 571


### setValueAt

572
setValueAt(index: number, value: T): void
L
linhaoran 已提交
573

574
替换容器中指定下标对应键值对中的键值。
L
linhaoran 已提交
575

Z
zengyawen 已提交
576 577
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
578
**参数:**
L
linhaoran 已提交
579

Z
zengyawen 已提交
580 581 582
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定替换数据下标。 |
583
| value | T | 是 | 替换键值对中的值。 |
L
linhaoran 已提交
584

L
liu-ganlin 已提交
585 586 587 588 589 590 591 592 593
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The setValueAt method cannot be bound. |
| 10200001 | The value of parameters are out of range. |

Z
zengyawen 已提交
594 595
**示例:**

596
```ts
Z
zengyawen 已提交
597
let plainArray = new PlainArray();
L
lengchangjing 已提交
598 599
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
Z
zengyawen 已提交
600
plainArray.setValueAt(1, 3546);
L
liu-ganlin 已提交
601
try {
L
liu-ganlin 已提交
602
  plainArray.setValueAt.bind({}, 1, 3546)(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
603 604 605 606 607 608 609 610
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
try {
  plainArray.setValueAt(10, 3);
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
611
```
L
linhaoran 已提交
612 613 614 615


### toString

Z
zengyawen 已提交
616
toString(): String
L
linhaoran 已提交
617 618 619

获取包含容器中所有键和值的字符串。

Z
zengyawen 已提交
620 621
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
622 623 624 625 626 627
**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| String | 返回对应字符串。 |

L
liu-ganlin 已提交
628 629 630 631 632 633 634 635
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The toString method cannot be bound. |

Z
zengyawen 已提交
636
**示例:**
L
linhaoran 已提交
637

638
```ts
Z
zengyawen 已提交
639
let plainArray = new PlainArray();
L
lengchangjing 已提交
640 641
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
642
let result = plainArray.toString();
L
liu-ganlin 已提交
643
try {
L
liu-ganlin 已提交
644
  plainArray.toString.bind({})(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
645 646 647
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
648
```
L
linhaoran 已提交
649 650 651 652


### clear

Z
zengyawen 已提交
653
clear(): void
L
linhaoran 已提交
654

Z
zengyawen 已提交
655
清除容器中的所有元素,并把length置为0。
L
linhaoran 已提交
656

Z
zengyawen 已提交
657 658
**系统能力:** SystemCapability.Utils.Lang

L
liu-ganlin 已提交
659 660 661 662 663 664 665 666
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The clear method cannot be bound. |

Z
zengyawen 已提交
667 668
**示例:**

669
```ts
Z
zengyawen 已提交
670
let plainArray = new PlainArray();
L
lengchangjing 已提交
671 672
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
Z
zengyawen 已提交
673
plainArray.clear();
L
liu-ganlin 已提交
674
try {
L
liu-ganlin 已提交
675
  plainArray.clear.bind({})(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
676 677 678
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
679
```
L
linhaoran 已提交
680 681 682 683


### forEach

684
forEach(callbackfn: (value: T, index?: number, PlainArray?: PlainArray&lt;T&gt;) => void, thisArg?: Object): void
L
linhaoran 已提交
685 686 687

通过回调函数来遍历实例对象上的元素以及元素对应的下标。

Z
zengyawen 已提交
688 689
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
690 691 692 693 694 695 696 697 698 699 700
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callbackfn | function | 是 | 回调函数。 |
| thisArg | Object | 否 | callbackfn被调用时用作this值。 |

callbackfn的参数说明:
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| value | T | 是 | 当前遍历到的元素键值对的值。 |
701
| index | number | 否 | 当前遍历到的元素键值对的键。 |
702
| PlainArray | PlainArray&lt;T&gt;| 否 | 当前调用forEach方法的实例对象。 |
Z
zengyawen 已提交
703

L
liu-ganlin 已提交
704 705 706 707 708 709 710 711
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The forEach method cannot be bound. |

Z
zengyawen 已提交
712 713
**示例:**

714
```ts
Z
zengyawen 已提交
715
let plainArray = new PlainArray();
L
lengchangjing 已提交
716 717
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
718 719
plainArray.forEach((value, index) => {
  console.log("value:" + value, index);
Z
zengyawen 已提交
720
});
L
liu-ganlin 已提交
721 722 723
try {
  plainArray.forEach.bind({}, (value, index) => {
    console.log("value:" + value, index);
L
liu-ganlin 已提交
724
  })(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
725 726 727
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
728
```
L
linhaoran 已提交
729 730 731 732


### [Symbol.iterator]

Z
zengyawen 已提交
733 734
[Symbol.iterator]\(): IterableIterator&lt;[number, T]&gt;

L
liu-ganlin 已提交
735
返回一个包含key-value键值对的迭代器对象,其中key是number类型。
Z
zengyawen 已提交
736

Z
zengyawen 已提交
737 738
**系统能力:** SystemCapability.Utils.Lang

Z
zengyawen 已提交
739 740 741 742
**返回值:**

| 类型 | 说明 |
| -------- | -------- |
743
| IterableIterator&lt;[number, T]&gt; | 返回一个迭代器。 |
Z
zengyawen 已提交
744

L
liu-ganlin 已提交
745 746 747 748 749 750 751 752
**错误码:**

以下错误码的详细介绍请参见[containers错误码](../errorcodes/errorcode-containers.md)

| 错误码ID | 错误码信息 |
| -------- | -------- |
| 10200011 | The Symbol.iterator method cannot be bound. |

Z
zengyawen 已提交
753 754
**示例:**

755
```ts
Z
zengyawen 已提交
756
let plainArray = new PlainArray();
L
lengchangjing 已提交
757 758
plainArray.add(1, "squirrel");
plainArray.add(2, "sparrow");
Z
zengyawen 已提交
759 760 761

// 使用方法一:
for (let item of plainArray) { 
L
liu-ganlin 已提交
762
  console.log("key:" + item[0]);
763
  console.log("value:" + item[1]);
Z
zengyawen 已提交
764 765 766 767 768 769
}

// 使用方法二:
let iter = plainArray[Symbol.iterator]();
let temp = iter.next().value;
while(temp != undefined) {
L
liu-ganlin 已提交
770
  console.log("key:" + temp[0]);
771
  console.log("value:" + temp[1]);
Z
zengyawen 已提交
772 773
  temp = iter.next().value;
}
L
liu-ganlin 已提交
774
try {
L
liu-ganlin 已提交
775
  plainArray[Symbol.iterator].bind({})(); // bind为JS标准内置对象Function的方法,用于改变this的指向,测试异常捕获
L
liu-ganlin 已提交
776 777 778
} catch(err) {
  console.log(`${err.code} - ${err.name} - ${err.message}`);
}
Z
zengyawen 已提交
779
```