> For the complete documentation index, see [llms.txt](https://move-book.com/llms.txt) # Vector `vector` is the only primitive collection type provided by Move. A `vector` is a homogeneous collection of `T`'s that can grow or shrink by pushing/popping values off the "end". A `vector` can be instantiated with any type `T`. For example, `vector`, `vector
`, `vector<0x42::my_module::MyData>`, and `vector>` are all valid vector types. ## Literals ### General `vector` Literals Vectors of any type can be created with `vector` literals. | Syntax | Type | Description | | --------------------- | ----------------------------------------------------------------------------- | ------------------------------------------ | | `vector[]` | `vector[]: vector` where `T` is any single, non-reference type | An empty vector | | `vector[e1, ..., en]` | `vector[e1, ..., en]: vector` where `e_i: T` s.t. `0 < i <= n` and `n > 0` | A vector with `n` elements (of length `n`) | In these cases, the type of the `vector` is inferred, either from the element type or from the vector's usage. If the type cannot be inferred, or simply for added clarity, the type can be specified explicitly: ```move vector[]: vector vector[e1, ..., en]: vector ``` #### Example Vector Literals ```move (vector[]: vector); (vector[0u8, 1u8, 2u8]: vector); (vector[]: vector); (vector
[@0x42, @0x100]: vector
); ``` ### `vector` literals A common use-case for vectors in Move is to represent "byte arrays", which are represented with `vector`. These values are often used for cryptographic purposes, such as a public key or a hash result. These values are so common that specific syntax is provided to make the values more readable, as opposed to having to use `vector[]` where each individual `u8` value is specified in numeric form. There are currently two supported types of `vector` literals, _byte strings_ and _hex strings_. #### Byte Strings Byte strings are quoted string literals prefixed by a `b`, e.g. `b"Hello!\n"`. These are ASCII encoded strings that allow for escape sequences. Currently, the supported escape sequences are: | Escape Sequence | Description | | --------------- | ---------------------------------------------- | | `\n` | New line (or Line feed) | | `\r` | Carriage return | | `\t` | Tab | | `\\` | Backslash | | `\0` | Null | | `\"` | Quote | | `\xHH` | Hex escape, inserts the hex byte sequence `HH` | #### Hex Strings Hex strings are quoted string literals prefixed by a `x`, e.g. `x"48656C6C6F210A"`. Each byte pair, ranging from `00` to `FF`, is interpreted as hex encoded `u8` value. So each byte pair corresponds to a single entry in the resulting `vector`. #### Example String Literals ```move fun byte_and_hex_strings() { assert!(b"" == x"", 0); assert!(b"Hello!\n" == x"48656C6C6F210A", 1); assert!(b"\x48\x65\x6C\x6C\x6F\x21\x0A" == x"48656C6C6F210A", 2); assert!( b"\"Hello\tworld!\"\n \r \\Null=\0" == x"2248656C6C6F09776F726C6421220A200D205C4E756C6C3D00", 3 ); } ``` ## Operations `vector` supports the following operations via the `std::vector` module in the Move standard library: | Function | Description | Aborts? | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | `vector::empty(): vector` | Create an empty vector that can store values of type `T` | Never | | `vector::singleton(t: T): vector` | Create a vector of size 1 containing `t` | Never | | `vector::push_back(v: &mut vector, t: T)` | Add `t` to the end of `v` | Never | | `vector::pop_back(v: &mut vector): T` | Remove and return the last element in `v` | If `v` is empty | | `vector::borrow(v: &vector, i: u64): &T` | Return an immutable reference to the `T` at index `i` | If `i` is not in bounds | | `vector::borrow_mut(v: &mut vector, i: u64): &mut T` | Return a mutable reference to the `T` at index `i` | If `i` is not in bounds | | `vector::destroy_empty(v: vector)` | Delete `v` | If `v` is not empty | | `vector::append(v1: &mut vector, v2: vector)` | Add the elements in `v2` to the end of `v1` | Never | | `vector::contains(v: &vector, e: &T): bool` | Return true if `e` is in the vector `v`. Otherwise, returns false | Never | | `vector::swap(v: &mut vector, i: u64, j: u64)` | Swaps the elements at the `i`th and `j`th indices in the vector `v` | If `i` or `j` is out of bounds | | `vector::reverse(v: &mut vector)` | Reverses the order of the elements in the vector `v` in place | Never | | `vector::index_of(v: &vector, e: &T): (bool, u64)` | Return `(true, i)` if `e` is in the vector `v` at index `i`. Otherwise, returns `(false, 0)` | Never | | `vector::remove(v: &mut vector, i: u64): T` | Remove the `i`th element of the vector `v`, shifting all subsequent elements. This is O(n) and preserves ordering of elements in the vector | If `i` is out of bounds | | `vector::swap_remove(v: &mut vector, i: u64): T` | Swap the `i`th element of the vector `v` with the last element and then pop the element, This is O(1), but does not preserve ordering of elements in the vector | If `i` is out of bounds | More operations may be added over time. ## Example ```move use std::vector; let mut v = vector::empty(); vector::push_back(&mut v, 5); vector::push_back(&mut v, 6); assert!(*vector::borrow(&v, 0) == 5, 42); assert!(*vector::borrow(&v, 1) == 6, 42); assert!(vector::pop_back(&mut v) == 6, 42); assert!(vector::pop_back(&mut v) == 5, 42); ``` ## Destroying and copying `vector`s Some behaviors of `vector` depend on the abilities of the element type, `T`. For example, vectors containing elements that do not have `drop` cannot be implicitly discarded like `v` in the example above--they must be explicitly destroyed with `vector::destroy_empty`. Note that `vector::destroy_empty` will abort at runtime unless `vec` contains zero elements: ```move fun destroy_any_vector(vec: vector) { vector::destroy_empty(vec) // deleting this line will cause a compiler error } ``` But no error would occur for dropping a vector that contains elements with `drop`: ```move fun destroy_droppable_vector(vec: vector) { // valid! // nothing needs to be done explicitly to destroy the vector } ``` Similarly, vectors cannot be copied unless the element type has `copy`. In other words, a `vector` has `copy` if and only if `T` has `copy`. Note that it will be implicitly copied if needed: ```move let x = vector[10]; let y = x; // implicit copy let z = x; (y, z) ``` Keep in mind, copies of large vectors can be expensive. If this is a concern, annotating the `intended` usage can prevent accidental copies. For example, ```move let x = vector[10]; let y = move x; let z = x; // ERROR! x has been moved (y, z) ``` For more details see the sections on [type abilities](./../abilities) and [generics](./../generics). ## Ownership As mentioned [above](#destroying-and-copying-vectors), `vector` values can be copied only if the elements can be copied. In that case, the copy can be done via a [`copy`](./../variables#move-and-copy) or a [dereference `*`](./references#reading-and-writing-through-references).