1# @ohos.util.PlainArray (非线性容器PlainArray) 2 3PlainArray可用于存储具有关联关系的key-value键值对集合,存储元素中key值唯一,key值类型为number类型,每个key对应一个value。 4 5PlainArray依据泛型定义,采用轻量级结构,集合中key值的查找依赖于二分查找算法,然后映射到其他数组中的value值。 6 7PlainArray和[LightWeightMap](js-apis-lightweightmap.md)都是用来存储键值对,且均采用轻量级结构,但PlainArray的key值类型只能为number类型。 8 9**推荐使用场景:** 当需要存储key值为number类型的键值对时,可以使用PlainArray。 10 11文档中存在泛型的使用,涉及以下泛型标记符:<br> 12- T:Type,类 13 14> **说明:** 15> 16> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 17 18 19## 导入模块 20 21```ts 22import { PlainArray } from '@kit.ArkTS'; 23``` 24 25 26## PlainArray 27 28### 属性 29 30**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 31 32**系统能力:** SystemCapability.Utils.Lang 33 34| 名称 | 类型 | 可读 | 可写 | 说明 | 35| -------- | -------- | -------- | -------- | -------- | 36| length | number | 是 | 否 | PlainArray的元素个数。 | 37 38 39### constructor 40 41constructor() 42 43PlainArray的构造函数。 44 45**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 46 47**系统能力:** SystemCapability.Utils.Lang 48 49**错误码:** 50 51以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 52 53| 错误码ID | 错误信息 | 54| -------- | -------- | 55| 10200012 | The PlainArray's constructor cannot be directly invoked. | 56 57**示例:** 58 59```ts 60let plainArray: PlainArray<string> = new PlainArray(); 61``` 62 63 64### isEmpty 65 66isEmpty(): boolean 67 68判断该容器是否为空。 69 70**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 71 72**系统能力:** SystemCapability.Utils.Lang 73 74**返回值:** 75 76| 类型 | 说明 | 77| -------- | -------- | 78| boolean | 为空返回true, 不为空返回false。 | 79 80**错误码:** 81 82以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 83 84| 错误码ID | 错误信息 | 85| -------- | -------- | 86| 10200011 | The isEmpty method cannot be bound. | 87 88**示例:** 89 90```ts 91const plainArray: PlainArray<string> = new PlainArray(); 92let result = plainArray.isEmpty(); 93``` 94 95 96### has 97 98has(key: number): boolean 99 100判断此容器中是否含有该指定key。 101 102**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 103 104**系统能力:** SystemCapability.Utils.Lang 105 106**参数:** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| -------- | -------- | -------- | -------- | 110| key | number | 是 | 指定key。需要小于等于int32_max即2147483647。 | 111 112**返回值:** 113 114| 类型 | 说明 | 115| -------- | -------- | 116| boolean | 包含指定key返回true,否则返回false。 | 117 118**错误码:** 119 120以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 121 122| 错误码ID | 错误信息 | 123| -------- | -------- | 124| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 125| 10200011 | The has method cannot be bound. | 126 127**示例:** 128 129```ts 130let plainArray: PlainArray<string> = new PlainArray(); 131plainArray.add(1, "squirrel"); 132let result = plainArray.has(1); 133``` 134 135 136### get 137 138get(key: number): T 139 140获取指定key所对应的value。 141 142**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 143 144**系统能力:** SystemCapability.Utils.Lang 145 146**参数:** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| -------- | -------- | -------- | -------- | 150| key | number | 是 | 查找的指定key。需要小于等于int32_max即2147483647。 | 151 152**返回值:** 153 154| 类型 | 说明 | 155| -------- | -------- | 156| T | 返回key映射的value值。 | 157 158**错误码:** 159 160以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 161 162| 错误码ID | 错误信息 | 163| -------- | -------- | 164| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 165| 10200011 | The get method cannot be bound. | 166 167**示例:** 168 169```ts 170let plainArray: PlainArray<string> = new PlainArray(); 171plainArray.add(1, "squirrel"); 172plainArray.add(2, "sparrow"); 173let result = plainArray.get(1); 174``` 175 176 177### getIndexOfKey 178 179getIndexOfKey(key: number): number 180 181查找指定key对应的下标值,如果没有找到该key返回-1。 182 183**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 184 185**系统能力:** SystemCapability.Utils.Lang 186 187**参数:** 188 189| 参数名 | 类型 | 必填 | 说明 | 190| -------- | -------- | -------- | -------- | 191| key | number | 是 | 指定key。需要小于等于int32_max即2147483647。 | 192 193**返回值:** 194 195| 类型 | 说明 | 196| -------- | -------- | 197| number | 返回指定key对应的下标值,查找失败返回-1。 | 198 199**错误码:** 200 201以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 202 203| 错误码ID | 错误信息 | 204| -------- | -------- | 205| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 206| 10200011 | The getIndexOfKey method cannot be bound. | 207 208**示例:** 209 210```ts 211let plainArray: PlainArray<string> = new PlainArray(); 212plainArray.add(1, "squirrel"); 213plainArray.add(2, "sparrow"); 214let result = plainArray.getIndexOfKey(2); 215``` 216 217 218### getIndexOfValue 219 220getIndexOfValue(value: T): number 221 222查找指定value元素第一次出现的下标值,如果没有找到该value元素返回-1。 223 224**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 225 226**系统能力:** SystemCapability.Utils.Lang 227 228**参数:** 229 230| 参数名 | 类型 | 必填 | 说明 | 231| -------- | -------- | -------- | -------- | 232| value | T | 是 | 指定value元素。 | 233 234**返回值:** 235 236| 类型 | 说明 | 237| -------- | -------- | 238| number | 返回指定value元素第一次出现时的下标值,查找失败返回-1。 | 239 240**错误码:** 241 242以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 243 244| 错误码ID | 错误信息 | 245| -------- | -------- | 246| 10200011 | The getIndexOfValue method cannot be bound. | 247 248**示例:** 249 250```ts 251let plainArray: PlainArray<string> = new PlainArray(); 252plainArray.add(1, "squirrel"); 253plainArray.add(2, "sparrow"); 254let result = plainArray.getIndexOfValue("squirrel"); 255``` 256 257 258### getKeyAt 259 260getKeyAt(index: number): number 261 262查找指定下标元素键值对中的key值。 263 264**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 265 266**系统能力:** SystemCapability.Utils.Lang 267 268**参数:** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| -------- | -------- | -------- | -------- | 272| index | number | 是 | 指定下标。需要小于等于int32_max即2147483647。 | 273 274**返回值:** 275 276| 类型 | 说明 | 277| -------- | -------- | 278| number | 返回该下标元素键值对中的key值,失败返回-1。 | 279 280**错误码:** 281 282以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 283 284| 错误码ID | 错误信息 | 285| -------- | -------- | 286| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 287| 10200011 | The getKeyAt method cannot be bound. | 288 289**示例:** 290 291```ts 292let plainArray: PlainArray<string> = new PlainArray(); 293plainArray.add(1, "squirrel"); 294plainArray.add(2, "sparrow"); 295let result = plainArray.getKeyAt(1); 296``` 297 298### getValueAt 299 300getValueAt(index: number): T 301 302查找指定下标元素键值对中的Value值,失败返回undefined。 303 304**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 305 306**系统能力:** SystemCapability.Utils.Lang 307 308**参数:** 309 310 | 参数名 | 类型 | 必填 | 说明 | 311 | -------- | -------- | -------- | -------- | 312 | index | number | 是 | 指定下标。需要小于等于int32_max即2147483647。 | 313 314**返回值:** 315 316 | 类型 | 说明 | 317 | -------- | -------- | 318 | T | 返回该下标元素键值对中的value值,失败返回undefined。 | 319 320 **错误码:** 321 322以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 323 324| 错误码ID | 错误信息 | 325| -------- | -------- | 326| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 327| 10200001 | The value of index is out of range. | 328| 10200011 | The getValueAt method cannot be bound. | 329 330**示例:** 331 332```ts 333let plainArray: PlainArray<string> = new PlainArray(); 334plainArray.add(1, "squirrel"); 335plainArray.add(2, "sparrow"); 336let result = plainArray.getValueAt(1); 337``` 338 339### clone 340 341clone(): PlainArray<T> 342 343克隆一个实例,并返回克隆后的实例。修改克隆后的实例并不会影响原实例。 344 345**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 346 347**系统能力:** SystemCapability.Utils.Lang 348 349**返回值:** 350 351| 类型 | 说明 | 352| -------- | -------- | 353| PlainArray<T> | 返回新的对象实例。 | 354 355**错误码:** 356 357以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 358 359| 错误码ID | 错误信息 | 360| -------- | -------- | 361| 10200011 | The clone method cannot be bound. | 362 363**示例:** 364 365```ts 366let plainArray: PlainArray<string> = new PlainArray(); 367plainArray.add(1, "squirrel"); 368plainArray.add(2, "sparrow"); 369let newPlainArray = plainArray.clone(); 370``` 371 372 373### add 374 375add(key: number, value: T): void 376 377向容器中添加一组数据。 378 379**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 380 381**系统能力:** SystemCapability.Utils.Lang 382 383**参数:** 384 385| 参数名 | 类型 | 必填 | 说明 | 386| -------- | -------- | -------- | -------- | 387| key | number | 是 | 添加成员数据的键名。需要小于等于int32_max即2147483647。 | 388| value | T | 是 | 添加成员数据的值。 | 389 390**错误码:** 391 392以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 393 394| 错误码ID | 错误信息 | 395| -------- | -------- | 396| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 397| 10200011 | The add method cannot be bound. | 398 399**示例:** 400 401```ts 402let plainArray: PlainArray<string> = new PlainArray(); 403plainArray.add(1, "squirrel"); 404``` 405 406 407### remove 408 409remove(key: number): T 410 411删除指定key对应的键值对。 412 413**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 414 415**系统能力:** SystemCapability.Utils.Lang 416 417**参数:** 418 419| 参数名 | 类型 | 必填 | 说明 | 420| -------- | -------- | -------- | -------- | 421| key | number | 是 | 指定key。需要小于等于int32_max即2147483647。 | 422 423**返回值:** 424 425| 类型 | 说明 | 426| -------- | -------- | 427| T | 返回所删除的键值对中的Value值。 | 428 429**错误码:** 430 431以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 432 433| 错误码ID | 错误信息 | 434| -------- | -------- | 435| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 436| 10200011 | The remove method cannot be bound. | 437 438**示例:** 439 440```ts 441let plainArray: PlainArray<string> = new PlainArray(); 442plainArray.add(1, "squirrel"); 443plainArray.add(2, "sparrow"); 444let result = plainArray.remove(2); 445``` 446 447 448### removeAt 449 450removeAt(index: number): T 451 452删除指定下标对应的元素。 453 454**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 455 456**系统能力:** SystemCapability.Utils.Lang 457 458**参数:** 459 460| 参数名 | 类型 | 必填 | 说明 | 461| -------- | -------- | -------- | -------- | 462| index | number | 是 | 指定元素下标。需要小于等于int32_max即2147483647。 | 463 464**返回值:** 465 466| 类型 | 说明 | 467| -------- | -------- | 468| T | 返回删除的元素。 | 469 470**错误码:** 471 472以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 473 474| 错误码ID | 错误信息 | 475| -------- | -------- | 476| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 477| 10200011 | The removeAt method cannot be bound. | 478 479**示例:** 480 481```ts 482let plainArray: PlainArray<string> = new PlainArray(); 483plainArray.add(1, "squirrel"); 484plainArray.add(2, "sparrow"); 485let result = plainArray.removeAt(1); 486``` 487 488 489### removeRangeFrom 490 491removeRangeFrom(index: number, size: number): number 492 493删除一定范围内的元素。 494 495**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 496 497**系统能力:** SystemCapability.Utils.Lang 498 499**参数:** 500 501| 参数名 | 类型 | 必填 | 说明 | 502| -------- | -------- | -------- | -------- | 503| index | number | 是 | 删除元素的起始下标。需要小于等于int32_max即2147483647。 | 504| size | number | 是 | 期望删除元素个数。需要小于等于int32_max即2147483647。 | 505 506**返回值:** 507 508| 类型 | 说明 | 509| -------- | -------- | 510| number | 实际删除元素个数。 | 511 512**错误码:** 513 514以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 515 516| 错误码ID | 错误信息 | 517| -------- | -------- | 518| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 519| 10200001 | The value of index is out of range. | 520| 10200011 | The removeRangeFrom method cannot be bound. | 521 522**示例:** 523 524```ts 525let plainArray: PlainArray<string> = new PlainArray(); 526plainArray.add(1, "squirrel"); 527plainArray.add(2, "sparrow"); 528let result = plainArray.removeRangeFrom(1, 3); 529``` 530 531 532### setValueAt 533 534setValueAt(index: number, value: T): void 535 536替换容器中指定下标对应键值对中的键值。 537 538**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 539 540**系统能力:** SystemCapability.Utils.Lang 541 542**参数:** 543 544| 参数名 | 类型 | 必填 | 说明 | 545| -------- | -------- | -------- | -------- | 546| index | number | 是 | 指定替换数据下标。需要小于等于int32_max即2147483647。 | 547| value | T | 是 | 替换键值对中的值。 | 548 549**错误码:** 550 551以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 552 553| 错误码ID | 错误信息 | 554| -------- | -------- | 555| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 556| 10200001 | The value of index is out of range. | 557| 10200011 | The setValueAt method cannot be bound. | 558 559**示例:** 560 561```ts 562let plainArray: PlainArray<string | number> = new PlainArray(); 563plainArray.add(1, "squirrel"); 564plainArray.add(2, "sparrow"); 565plainArray.setValueAt(1, 3546); 566``` 567 568 569### toString 570 571toString(): String 572 573获取包含容器中所有键和值的字符串。 574 575**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 576 577**系统能力:** SystemCapability.Utils.Lang 578 579**返回值:** 580 581| 类型 | 说明 | 582| -------- | -------- | 583| String | 返回对应字符串。 | 584 585**错误码:** 586 587以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 588 589| 错误码ID | 错误信息 | 590| -------- | -------- | 591| 10200011 | The toString method cannot be bound. | 592 593**示例:** 594 595```ts 596let plainArray: PlainArray<string> = new PlainArray(); 597plainArray.add(1, "squirrel"); 598plainArray.add(2, "sparrow"); 599let result = plainArray.toString(); 600``` 601 602 603### clear 604 605clear(): void 606 607清除容器中的所有元素,并把length置为0。 608 609**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 610 611**系统能力:** SystemCapability.Utils.Lang 612 613**错误码:** 614 615以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 616 617| 错误码ID | 错误信息 | 618| -------- | -------- | 619| 10200011 | The clear method cannot be bound. | 620 621**示例:** 622 623```ts 624let plainArray: PlainArray<string> = new PlainArray(); 625plainArray.add(1, "squirrel"); 626plainArray.add(2, "sparrow"); 627plainArray.clear(); 628``` 629 630 631### forEach 632 633forEach(callbackFn: (value: T, index?: number, PlainArray?: PlainArray<T>) => void, thisArg?: Object): void 634 635通过回调函数来遍历实例对象上的元素以及元素对应的下标。 636 637**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 638 639**系统能力:** SystemCapability.Utils.Lang 640 641**参数:** 642 643| 参数名 | 类型 | 必填 | 说明 | 644| -------- | -------- | -------- | -------- | 645| callbackFn | function | 是 | 回调函数。 | 646| thisArg | Object | 否 | callbackfn被调用时用作this值,默认值为当前实例对象。 | 647 648callbackfn的参数说明: 649| 参数名 | 类型 | 必填 | 说明 | 650| -------- | -------- | -------- | -------- | 651| value | T | 是 | 当前遍历到的元素。 | 652| index | number | 否 | 当前遍历到的下标值,默认值为0。 | 653| PlainArray | PlainArray<T>| 否 | 当前调用forEach方法的实例对象,默认值为当前实例对象。 | 654 655**错误码:** 656 657以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 658 659| 错误码ID | 错误信息 | 660| -------- | -------- | 661| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 662| 10200011 | The forEach method cannot be bound. | 663 664**示例:** 665 666```ts 667let plainArray: PlainArray<string> = new PlainArray(); 668plainArray.add(1, "squirrel"); 669plainArray.add(2, "sparrow"); 670plainArray.forEach((value: string, index?: number) => { 671 console.log("value:" + value, "index:" + index); 672}); 673``` 674```ts 675// 不建议在forEach中使用add、remove、removeAt方法,会导致死循环等不可预知的风险,可使用for循环来进行插入和删除。 676let plainArray: PlainArray<string> = new PlainArray(); 677for(let i = 0;i < 10;i++) { 678 plainArray.add(i,"123"); 679} 680 681for(let i = 0;i < 10;i++) { 682 plainArray.remove(i); 683} 684``` 685 686### [Symbol.iterator] 687 688[Symbol.iterator]\(): IterableIterator<[number, T]> 689 690返回一个包含key-value键值对的迭代器对象,其中key是number类型。 691 692**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 693 694**系统能力:** SystemCapability.Utils.Lang 695 696**返回值:** 697 698| 类型 | 说明 | 699| -------- | -------- | 700| IterableIterator<[number, T]> | 返回一个迭代器。 | 701 702**错误码:** 703 704以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 705 706| 错误码ID | 错误信息 | 707| -------- | -------- | 708| 10200011 | The Symbol.iterator method cannot be bound. | 709 710**示例:** 711 712```ts 713let plainArray: PlainArray<string> = new PlainArray(); 714plainArray.add(1, "squirrel"); 715plainArray.add(2, "sparrow"); 716 717let iter = plainArray[Symbol.iterator](); 718let temp: IteratorResult<Object[]> = iter.next(); 719while(!temp.done) { 720 console.log("key:" + temp.value[0]); 721 console.log("value:" + temp.value[1]); 722 temp = iter.next(); 723} 724``` 725```ts 726// 不建议在Symbol.iterator中使用add、remove、removeAt方法,会导致死循环等不可预知的风险,可使用for循环来进行插入和删除。 727let plainArray: PlainArray<string> = new PlainArray(); 728for(let i = 0;i < 10;i++) { 729 plainArray.add(i,"123"); 730} 731 732for(let i = 0;i < 10;i++) { 733 plainArray.remove(i); 734} 735```