1# @ohos.util.Vector (Linear Container Vector)
2
3**Vector** 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### Attributes
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 (called container later).|
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 container.
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 | Returns **true** if the element is added successfully; returns **false** otherwise.|
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 container 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 | Returns **true** if the container has the specified element; returns **false** otherwise.|
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 container.
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 | Returns the position index if obtained; returns **-1** otherwise.|
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 container.
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 | Returns the position index if obtained; returns **-1** otherwise.|
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 container 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 container.
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 | Returns **true** if the element is removed successfully; returns **false** otherwise.|
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 container 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&lt;T&gt;) => T,
300thisArg?: Object): void
301
302Replaces all elements in this container 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&lt;T&gt; | 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&lt;T&gt;) => void,
338thisArg?: Object): void
339
340Uses a callback to traverse the elements in this container 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&lt;T&gt; | 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 container.
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&lt;T&gt;
409
410Obtains elements within a range in this container, 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&lt;T&gt; | 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 container 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&lt;T&gt;
464
465Clones this container 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&lt;T&gt; | 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 container.
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&lt;T&gt;
514
515Converts this container into an array.
516
517**System capability**: SystemCapability.Utils.Lang
518
519**Return value**
520
521| Type| Description|
522| -------- | -------- |
523| Array&lt;T&gt; | 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 container is empty (contains no elements).
541
542**System capability**: SystemCapability.Utils.Lang
543
544**Return value**
545
546| Type| Description|
547| -------- | -------- |
548| boolean | Returns **true** if the container is empty; returns **false** otherwise.|
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 container.
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 container 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 container 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&lt;T&gt;): void
634
635Copies elements in this container 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&lt;T&gt; | Yes| Array to which the elements in the container will be copied.|
644
645### getFirstElement
646
647getFirstElement(): T
648
649Obtains the first element in this container.
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 container.
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 | Returns the position index if obtained; returns **-1** otherwise.|
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 | Returns the position index if obtained; returns **-1** otherwise.|
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 container.
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 container.
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 container 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&lt;T&gt;
840
841Obtains an iterator. Each item of the iterator is a JavaScript object.
842
843**System capability**: SystemCapability.Utils.Lang
844
845**Return value**
846| Type| Description|
847| -------- | -------- |
848| IterableIterator&lt;T&gt; | 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