1# @ohos.util.Vector (Linear Container Vector) 2 3Vector is a linear data structure that is implemented based on arrays. When the memory of a vector is used up, a larger contiguous memory area is automatically allocated, all the elements are copied to the new memory area, and the current memory area is reclaimed. Vector can be used to efficiently access elements. 4 5Both Vector and [ArrayList](js-apis-arraylist.md) are implemented based on arrays, but Vector provides more interfaces for operating the arrays. Both of them can dynamically adjust the capacity. Vector doubles the capacity each time, whereas ArrayList increases the capacity by 50%. 6 7**Recommended use case**: Use Vector when the data volume is large. 8 9This topic uses the following to identify the use of generics: 10- T: Type 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15> 16> The APIs provided by this module are deprecated since API version 9. You are advised to use [@ohos.util.ArrayList](js-apis-arraylist.md). 17 18## Modules to Import 19 20```ts 21import { Vector } from '@kit.ArkTS'; 22``` 23 24 25## Vector 26 27### Properties 28 29**System capability**: SystemCapability.Utils.Lang 30 31| Name| Type| Readable| Writable| Description| 32| -------- | -------- | -------- | -------- | -------- | 33| length | number | Yes| No| Number of elements in a Vector.| 34 35 36### constructor 37 38constructor() 39 40A constructor used to create a **Vector** instance. 41 42**System capability**: SystemCapability.Utils.Lang 43 44**Example** 45 46```ts 47let vector : Vector<string | number | Array<number>> = new Vector(); 48``` 49 50 51### add 52 53add(element: T): boolean 54 55Adds an element at the end of this Vector. 56 57**System capability**: SystemCapability.Utils.Lang 58 59**Parameters** 60 61| Name| Type| Mandatory| Description| 62| -------- | -------- | -------- | -------- | 63| element | T | Yes| Target element.| 64 65**Return value** 66 67| Type| Description| 68| -------- | -------- | 69| boolean | Operation result. The value **true** is returned if the element is added; otherwise, **false** is returned.| 70 71**Example** 72 73```ts 74class C1 { 75 name: string = "" 76 age: string = "" 77} 78let vector : Vector<string | number | C1 | Array<number>> = new Vector(); 79let result = vector.add("a"); 80let result1 = vector.add(1); 81let b = [1, 2, 3]; 82let result2 = vector.add(b); 83let c: C1 = {name : "Jack", age : "13"}; 84let result3 = vector.add(c); 85``` 86 87### insert 88 89insert(element: T, index: number): void 90 91Inserts an element within the length range and moves its subsequent elements rightwards. 92 93**System capability**: SystemCapability.Utils.Lang 94 95**Parameters** 96 97| Name| Type| Mandatory| Description| 98| -------- | -------- | -------- | -------- | 99| element | T | Yes| Target element.| 100| index | number | Yes| Index of the position where the element is to be inserted.| 101 102**Example** 103 104```ts 105let vector : Vector<string | number | Object | Array<number>> = new Vector(); 106vector.insert("A", 0); 107vector.insert(0, 1); 108vector.insert(true, 2); 109``` 110 111### has 112 113has(element: T): boolean 114 115Checks whether this Vector has the specified element. 116 117**System capability**: SystemCapability.Utils.Lang 118 119**Parameters** 120 121| Name| Type| Mandatory| Description| 122| -------- | -------- | -------- | -------- | 123| element | T | Yes| Target element.| 124 125**Return value** 126 127| Type| Description| 128| -------- | -------- | 129| boolean | Check result. The value **true** is returned if the Vector has the specified element; otherwise, **false** is returned.| 130 131**Example** 132 133```ts 134let vector : Vector<string> = new Vector(); 135let result = vector.has("squirrel"); 136vector.add("squirrel"); 137let result1 = vector.has("squirrel"); 138``` 139 140### getIndexOf 141 142getIndexOf(element: T): number 143 144Obtains the index of the first occurrence of the specified element in this Vector. 145 146**System capability**: SystemCapability.Utils.Lang 147 148**Parameters** 149 150| Name| Type| Mandatory| Description| 151| -------- | -------- | -------- | -------- | 152| element | T | Yes| Target element.| 153 154**Return value** 155 156| Type| Description| 157| -------- | -------- | 158| number | Index of the element. If no match is found, **-1** is returned.| 159 160**Example** 161 162```ts 163let vector : Vector<number> = new Vector(); 164vector.add(2); 165vector.add(4); 166vector.add(5); 167vector.add(2); 168vector.add(1); 169vector.add(2); 170vector.add(4); 171let result = vector.getIndexOf(2); 172``` 173 174### getLastIndexOf 175 176getLastIndexOf(element: T): number 177 178Obtains the index of the last occurrence of the specified element in this Vector. 179 180**System capability**: SystemCapability.Utils.Lang 181 182**Parameters** 183 184| Name| Type| Mandatory| Description| 185| -------- | -------- | -------- | -------- | 186| element | T | Yes| Target element.| 187 188**Return value** 189 190| Type| Description| 191| -------- | -------- | 192| number | Index of the element. If no match is found, **-1** is returned.| 193 194**Example** 195 196```ts 197let vector : Vector<number> = new Vector(); 198vector.add(2); 199vector.add(4); 200vector.add(5); 201vector.add(2); 202vector.add(1); 203vector.add(2); 204vector.add(4); 205let result = vector.getLastIndexOf(2); 206``` 207 208### removeByIndex 209 210removeByIndex(index: number): T 211 212Searches for an element based on its index, removes the element after returning it, and moves its subsequent elements leftwards. 213 214**System capability**: SystemCapability.Utils.Lang 215 216**Parameters** 217 218| Name| Type| Mandatory| Description| 219| -------- | -------- | -------- | -------- | 220| index | number | Yes| Position index of the target element.| 221 222**Return value** 223 224| Type| Description| 225| -------- | -------- | 226| T | Element removed. If the Vector is empty, **undefined** is returned. If the index is out of range, an exception is thrown.| 227 228**Example** 229 230```ts 231let vector : Vector<number> = new Vector(); 232vector.add(2); 233vector.add(4); 234vector.add(5); 235vector.add(2); 236vector.add(4); 237let result = vector.removeByIndex(2); 238``` 239 240### remove 241 242remove(element: T): boolean 243 244Removes the first occurrence of the specified element from this Vector. 245 246**System capability**: SystemCapability.Utils.Lang 247 248**Parameters** 249 250| Name| Type| Mandatory| Description| 251| -------- | -------- | -------- | -------- | 252| element | T | Yes| Target element.| 253 254**Return value** 255 256| Type| Description| 257| -------- | -------- | 258| boolean | Operation result. The value **true** is returned if the element is removed; otherwise, **false** is returned.| 259 260**Example** 261 262```ts 263let vector : Vector<number> = new Vector(); 264vector.add(2); 265vector.add(4); 266vector.add(5); 267vector.add(4); 268let result = vector.remove(2); 269``` 270 271### removeByRange 272 273removeByRange(fromIndex: number, toIndex: number): void 274 275Removes from this Vector all of the elements within a range, including the element at the start position but not that at the end position. 276 277**System capability**: SystemCapability.Utils.Lang 278 279**Parameters** 280 281| Name| Type| Mandatory| Description| 282| -------- | -------- | -------- | -------- | 283| fromIndex | number | Yes| Index of the start position.| 284| toIndex | number | Yes| Index of the end position.| 285 286**Example** 287 288```ts 289let vector : Vector<number> = new Vector(); 290vector.add(2); 291vector.add(4); 292vector.add(5); 293vector.add(4); 294vector.removeByRange(2,4); 295``` 296 297### replaceAllElements 298 299replaceAllElements(callbackFn: (value: T, index?: number, vector?: Vector<T>) => T, 300thisArg?: Object): void 301 302Replaces all elements in this Vector with new elements, and returns the new ones. 303 304**System capability**: SystemCapability.Utils.Lang 305 306**Parameters** 307 308| Name| Type| Mandatory| Description| 309| -------- | -------- | -------- | -------- | 310| callbackFn | function | Yes| Callback invoked for replacement.| 311| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this instance.| 312 313callbackFn 314 315| Name| Type| Mandatory| Description| 316| -------- | -------- | -------- | -------- | 317| value | T | Yes| Value of the element that is currently traversed.| 318| index | number | No| Position index of the element that is currently traversed. The default value is **0**.| 319| vector | Vector<T> | No| Instance that calls the **replaceAllElements** API. The default value is this instance.| 320 321**Example** 322 323```ts 324let vector : Vector<number> = new Vector(); 325vector.add(2); 326vector.add(4); 327vector.add(5); 328vector.add(4); 329vector.replaceAllElements((value : number) : number => { 330 // Add the user operation logic based on the actual scenario. 331 return value; 332}); 333``` 334 335### forEach 336 337forEach(callbackFn: (value: T, index?: number, vector?: Vector<T>) => void, 338thisArg?: Object): void 339 340Uses a callback to traverse the elements in this Vector and obtain their position indexes. 341 342**System capability**: SystemCapability.Utils.Lang 343 344**Parameters** 345 346| Name| Type| Mandatory| Description| 347| -------- | -------- | -------- | -------- | 348| callbackFn | function | Yes| Callback invoked for replacement.| 349| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this instance.| 350 351callbackFn 352 353| Name| Type| Mandatory| Description| 354| -------- | -------- | -------- | -------- | 355| value | T | Yes| Value of the element that is currently traversed.| 356| index | number | No| Position index of the element that is currently traversed. The default value is **0**.| 357| vector | Vector<T> | No| Instance that calls the **forEach** API. The default value is this instance.| 358 359**Example** 360 361```ts 362let vector : Vector<number> = new Vector(); 363vector.add(2); 364vector.add(4); 365vector.add(5); 366vector.add(4); 367vector.forEach((value : number, index ?: number) : void => { 368 console.log("value:" + value, "index:" + index); 369}); 370``` 371 372### sort 373 374sort(comparator?: (firstValue: T, secondValue: T) => number): void 375 376Sorts elements in this Vector. 377 378**System capability**: SystemCapability.Utils.Lang 379 380**Parameters** 381 382| Name| Type| Mandatory| Description| 383| -------- | -------- | -------- | -------- | 384| comparator | function | No| Callback invoked for sorting. The default value is this instance.| 385 386comparator 387 388| Name| Type| Mandatory| Description| 389| -------- | -------- | -------- | -------- | 390| firstValue | T | Yes| Previous element.| 391| secondValue | T | Yes| Next element.| 392 393**Example** 394 395```ts 396let vector : Vector<number> = new Vector(); 397vector.add(2); 398vector.add(4); 399vector.add(5); 400vector.add(4); 401vector.sort((a: number, b: number) => a - b); 402vector.sort((a: number, b: number) => b - a); 403vector.sort(); 404``` 405 406### subVector 407 408subVector(fromIndex: number, toIndex: number): Vector<T> 409 410Obtains elements within a range in this Vector, including the element at the start position but not that at the end position, and returns these elements as a new **Vector** instance. 411 412**System capability**: SystemCapability.Utils.Lang 413 414**Parameters** 415 416| Name| Type| Mandatory| Description| 417| -------- | -------- | -------- | -------- | 418| fromIndex | number | Yes| Index of the start position.| 419| toIndex | number | Yes| Index of the end position.| 420 421**Return value** 422 423| Type| Description| 424| -------- | -------- | 425| Vector<T> | New **Vector** instance obtained.| 426 427**Example** 428 429```ts 430let vector : Vector<number> = new Vector(); 431vector.add(2); 432vector.add(4); 433vector.add(5); 434vector.add(4); 435vector.add(6); 436vector.add(8); 437let result = vector.subVector(0,4); 438let result1 = vector.subVector(2,4); 439 440``` 441 442### clear 443 444clear(): void 445 446Clears all elements in this Vector and sets its length to **0**. 447 448**System capability**: SystemCapability.Utils.Lang 449 450**Example** 451 452```ts 453let vector : Vector<number> = new Vector(); 454vector.add(2); 455vector.add(4); 456vector.add(5); 457vector.add(4); 458vector.clear(); 459``` 460 461### clone 462 463clone(): Vector<T> 464 465Clones this Vector and returns a copy. The modification to the copy does not affect the original instance. 466 467**System capability**: SystemCapability.Utils.Lang 468 469**Return value** 470 471| Type| Description| 472| -------- | -------- | 473| Vector<T> | New **Vector** instance obtained.| 474 475**Example** 476 477```ts 478let vector : Vector<number> = new Vector(); 479vector.add(2); 480vector.add(4); 481vector.add(5); 482vector.add(4); 483let result = vector.clone(); 484``` 485 486### getCapacity 487 488getCapacity(): number 489 490Obtains the capacity of this Vector. 491 492**System capability**: SystemCapability.Utils.Lang 493 494**Return value** 495 496| Type| Description| 497| -------- | -------- | 498| number | Capacity obtained.| 499 500**Example** 501 502```ts 503let vector : Vector<number> = new Vector(); 504vector.add(2); 505vector.add(4); 506vector.add(5); 507vector.add(4); 508let result = vector.getCapacity(); 509``` 510 511### convertToArray 512 513convertToArray(): Array<T> 514 515Converts this Vector into an array. 516 517**System capability**: SystemCapability.Utils.Lang 518 519**Return value** 520 521| Type| Description| 522| -------- | -------- | 523| Array<T> | Array obtained.| 524 525**Example** 526 527```ts 528let vector : Vector<number> = new Vector(); 529vector.add(2); 530vector.add(4); 531vector.add(5); 532vector.add(4); 533let result = vector.convertToArray(); 534``` 535 536### isEmpty 537 538isEmpty(): boolean 539 540Checks whether this Vector is empty (contains no elements). 541 542**System capability**: SystemCapability.Utils.Lang 543 544**Return value** 545 546| Type| Description| 547| -------- | -------- | 548| boolean | Check result. The value **true** is returned if the Vector is empty; otherwise, **false** is returned.| 549 550**Example** 551 552```ts 553let vector : Vector<number> = new Vector(); 554vector.add(2); 555vector.add(4); 556vector.add(5); 557vector.add(4); 558let result = vector.isEmpty(); 559``` 560 561### increaseCapacityTo 562 563increaseCapacityTo(newCapacity: number): void 564 565Increases the capacity of this Vector. 566 567**System capability**: SystemCapability.Utils.Lang 568 569**Parameters** 570 571| Name| Type| Mandatory| Description| 572| -------- | -------- | -------- | -------- | 573| newCapacity | number | Yes| New capacity.| 574 575**Example** 576 577```ts 578let vector : Vector<number> = new Vector(); 579vector.add(2); 580vector.add(4); 581vector.add(5); 582vector.add(4); 583vector.increaseCapacityTo(2); 584vector.increaseCapacityTo(12); 585``` 586 587### trimToCurrentLength 588 589trimToCurrentLength(): void 590 591Trims the capacity of this Vector into its current length. 592 593**System capability**: SystemCapability.Utils.Lang 594 595**Example** 596 597```ts 598let vector : Vector<number> = new Vector(); 599vector.add(2); 600vector.add(4); 601vector.add(5); 602vector.add(4); 603vector.trimToCurrentLength(); 604``` 605 606### toString 607 608toString(): string 609 610Uses commas (,) to concatenate elements in this Vector into a string. 611 612**System capability**: SystemCapability.Utils.Lang 613 614**Return value** 615 616| Type| Description| 617| -------- | -------- | 618| string | String obtained.| 619 620**Example** 621 622```ts 623let vector : Vector<number> = new Vector(); 624vector.add(2); 625vector.add(4); 626vector.add(5); 627vector.add(4); 628let result = vector.toString(); 629``` 630 631### copyToArray 632 633copyToArray(array: Array<T>): void 634 635Copies elements in this Vector into an array to overwrite elements of the same position indexes. 636 637**System capability**: SystemCapability.Utils.Lang 638 639**Parameters** 640 641| Name| Type| Mandatory| Description| 642| -------- | -------- | -------- | -------- | 643| array | Array<T> | Yes| Array to which the elements in the Vector will be copied.| 644 645### getFirstElement 646 647getFirstElement(): T 648 649Obtains the first element in this Vector. 650 651**System capability**: SystemCapability.Utils.Lang 652 653**Return value** 654 655| Type| Description| 656| -------- | -------- | 657| T | The first element obtained.| 658 659**Example** 660 661```ts 662let vector : Vector<number> = new Vector(); 663vector.add(2); 664vector.add(4); 665vector.add(5); 666vector.add(4); 667let result = vector.getFirstElement(); 668``` 669 670### getLastElement 671 672getLastElement(): T 673 674Obtains the last element in this Vector. 675 676**System capability**: SystemCapability.Utils.Lang 677 678**Return value** 679 680| Type| Description| 681| -------- | -------- | 682| T | The last element obtained.| 683 684**Example** 685 686```ts 687let vector : Vector<number> = new Vector(); 688vector.add(2); 689vector.add(4); 690vector.add(5); 691vector.add(4); 692let result = vector.getLastElement(); 693``` 694 695### getLastIndexFrom 696 697getLastIndexFrom(element: T, index: number): number 698 699Searches for an element backward from the specified position index and returns the position index of the element. 700 701**System capability**: SystemCapability.Utils.Lang 702 703**Parameters** 704 705| Name| Type| Mandatory| Description| 706| -------- | -------- | -------- | -------- | 707| element | T | Yes| Target element.| 708| index | number | Yes| Position index where the search starts.| 709 710**Return value** 711 712| Type| Description| 713| -------- | -------- | 714| number | Index of the element. If no match is found, **-1** is returned.| 715 716**Example** 717 718```ts 719let vector : Vector<number> = new Vector(); 720vector.add(2); 721vector.add(4); 722vector.add(5); 723vector.add(4); 724let result = vector.getLastIndexFrom(4,3); 725``` 726 727### getIndexFrom 728 729getIndexFrom(element: T, index: number): number 730 731Searches for an element forward from the specified position index and returns the position index of the element. 732 733**System capability**: SystemCapability.Utils.Lang 734 735**Parameters** 736 737| Name| Type| Mandatory| Description| 738| -------- | -------- | -------- | -------- | 739| element | T | Yes| Target element.| 740| index | number | Yes| Position index where the search starts.| 741 742**Return value** 743 744| Type| Description| 745| -------- | -------- | 746| number | Index of the element. If no match is found, **-1** is returned.| 747 748**Example** 749 750```ts 751let vector : Vector<number> = new Vector(); 752vector.add(2); 753vector.add(4); 754vector.add(5); 755vector.add(4); 756let result = vector.getIndexFrom(4, 3); 757``` 758 759### setLength 760 761setLength(newSize: number): void 762 763Sets a new length for this Vector. 764 765**System capability**: SystemCapability.Utils.Lang 766 767**Parameters** 768 769| Name| Type| Mandatory| Description| 770| -------- | -------- | -------- | -------- | 771| newSize | number | Yes| New length to set.| 772 773**Example** 774 775```ts 776let vector : Vector<number> = new Vector(); 777vector.add(2); 778vector.add(4); 779vector.add(5); 780vector.add(4); 781vector.setLength(8); 782vector.setLength(2); 783``` 784 785### get 786 787get(index: number): T 788 789Obtains an element at the specified position in this Vector. 790 791**System capability**: SystemCapability.Utils.Lang 792 793**Parameters** 794 795 | Name| Type| Mandatory| Description| 796 | -------- | -------- | -------- | -------- | 797 | index | number | Yes| Position index of the target element.| 798 799**Return value** 800 801 | Type| Description| 802 | -------- | -------- | 803 | T | Element obtained.| 804 805**Example** 806 807```ts 808let vector : Vector<number> = new Vector(); 809vector.add(2); 810vector.add(4); 811vector.add(5); 812vector.add(4); 813let result = vector.get(2); 814``` 815 816### set 817 818set(index: number, element: T): T 819 820Replaces an element at the specified position in this Vector with a given element. 821 822**System capability**: SystemCapability.Utils.Lang 823 824**Parameters** 825 826| Name| Type| Mandatory| Description| 827| -------- | -------- | -------- | -------- | 828| index | number | Yes| Position index of the target element.| 829| element | T | Yes| Element to be used for replacement.| 830 831**Return value** 832 833 | Type| Description| 834 | -------- | -------- | 835 | T | New element.| 836 837### [Symbol.iterator] 838 839[Symbol.iterator]\(): IterableIterator<T> 840 841Returns an iterator, each item of which is a JavaScript object. 842 843**System capability**: SystemCapability.Utils.Lang 844 845**Return value** 846| Type| Description| 847| -------- | -------- | 848| IterableIterator<T> | Iterator obtained.| 849 850**Example** 851 852```ts 853let vector : Vector<number> = new Vector(); 854vector.add(2); 855vector.add(4); 856vector.add(5); 857vector.add(4); 858// Method 1: 859let nums: Array<number> = vector.convertToArray() 860for (let item of nums) { 861 console.log("value:" + item); 862} 863 864// Method 2: 865let iter = vector[Symbol.iterator](); 866let temp: IteratorResult<number> = iter.next().value; 867while(temp != undefined) { 868 console.log("value:" + temp); 869 temp = iter.next().value; 870} 871``` 872