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