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