Struct im::Vector

source · []
pub struct Vector<A> { /* private fields */ }
Expand description

A persistent vector.

This is a sequence of elements in insertion order - if you need a list of things, any kind of list of things, this is what you’re looking for.

It’s implemented as an RRB vector with smart head/tail chunking. In performance terms, this means that practically every operation is O(log n), except push/pop on both sides, which will be O(1) amortised, and O(log n) in the worst case. In practice, the push/pop operations will be blindingly fast, nearly on par with the native VecDeque, and other operations will have decent, if not high, performance, but they all have more or less the same O(log n) complexity, so you don’t need to keep their performance characteristics in mind - everything, even splitting and merging, is safe to use and never too slow.

Performance Notes

Because of the head/tail chunking technique, until you push a number of items above double the tree’s branching factor (that’s self.len() = 2 × k (where k = 64) = 128) on either side, the data structure is still just a handful of arrays, not yet an RRB tree, so you’ll see performance and memory characteristics similar to Vec or VecDeque.

This means that the structure always preallocates four chunks of size k (k being the tree’s branching factor), equivalent to a Vec with an initial capacity of 256. Beyond that, it will allocate tree nodes of capacity k as needed.

In addition, vectors start out as single chunks, and only expand into the full data structure once you go past the chunk size. This makes them perform identically to Vec at small sizes.

Implementations

Construct an empty vector.

Get the length of a vector.

Time: O(1)

Examples
assert_eq!(5, vector![1, 2, 3, 4, 5].len());

Test whether a vector is empty.

Time: O(1)

Examples
let vec = vector!["Joe", "Mike", "Robert"];
assert_eq!(false, vec.is_empty());
assert_eq!(true, Vector::<i32>::new().is_empty());

Test whether a vector is currently inlined.

Vectors small enough that their contents could be stored entirely inside the space of std::mem::size_of::<Vector<A>>() bytes are stored inline on the stack instead of allocating any chunks. This method returns true if this vector is currently inlined, or false if it currently has chunks allocated on the heap.

This may be useful in conjunction with ptr_eq(), which checks if two vectors’ heap allocations are the same, and thus will never return true for inlined vectors.

Time: O(1)

Test whether two vectors refer to the same content in memory.

This uses the following rules to determine equality:

  • If the two sides are references to the same vector, return true.
  • If the two sides are single chunk vectors pointing to the same chunk, return true.
  • If the two sides are full trees pointing to the same chunks, return true.

This would return true if you’re comparing a vector to itself, or if you’re comparing a vector to a fresh clone of itself. The exception to this is if you’ve cloned an inline array (ie. an array with so few elements they can fit inside the space a Vector allocates for its pointers, so there are no heap allocations to compare).

Time: O(1)

Get an iterator over a vector.

Time: O(1)

Get a mutable iterator over a vector.

Time: O(1)

Get an iterator over the leaf nodes of a vector.

This returns an iterator over the Chunks at the leaves of the RRB tree. These are useful for efficient parallelisation of work on the vector, but should not be used for basic iteration.

Time: O(1)

Get a mutable iterator over the leaf nodes of a vector. This returns an iterator over the Chunks at the leaves of the RRB tree. These are useful for efficient parallelisation of work on the vector, but should not be used for basic iteration.

Time: O(1)

Construct a Focus for a vector.

Time: O(1)

Construct a FocusMut for a vector.

Time: O(1)

Get a reference to the value at index index in a vector.

Returns None if the index is out of bounds.

Time: O(log n)

Examples
let vec = vector!["Joe", "Mike", "Robert"];
assert_eq!(Some(&"Robert"), vec.get(2));
assert_eq!(None, vec.get(5));

Get a mutable reference to the value at index index in a vector.

Returns None if the index is out of bounds.

Time: O(log n)

Examples
let mut vec = vector!["Joe", "Mike", "Robert"];
{
    let robert = vec.get_mut(2).unwrap();
    assert_eq!(&mut "Robert", robert);
    *robert = "Bjarne";
}
assert_eq!(vector!["Joe", "Mike", "Bjarne"], vec);

Get the first element of a vector.

If the vector is empty, None is returned.

Time: O(log n)

Get a mutable reference to the first element of a vector.

If the vector is empty, None is returned.

Time: O(log n)

Get the first element of a vector.

If the vector is empty, None is returned.

This is an alias for the front method.

Time: O(log n)

Get the last element of a vector.

If the vector is empty, None is returned.

Time: O(log n)

Get a mutable reference to the last element of a vector.

If the vector is empty, None is returned.

Time: O(log n)

Get the last element of a vector.

If the vector is empty, None is returned.

This is an alias for the back method.

Time: O(log n)

Get the index of a given element in the vector.

Searches the vector for the first occurrence of a given value, and returns the index of the value if it’s there. Otherwise, it returns None.

Time: O(n)

Examples
let mut vec = vector![1, 2, 3, 4, 5];
assert_eq!(Some(2), vec.index_of(&3));
assert_eq!(None, vec.index_of(&31337));

Test if a given element is in the vector.

Searches the vector for the first occurrence of a given value, and returns true if it’s there. If it’s nowhere to be found in the vector, it returns false.

Time: O(n)

Examples
let mut vec = vector![1, 2, 3, 4, 5];
assert_eq!(true, vec.contains(&3));
assert_eq!(false, vec.contains(&31337));

Discard all elements from the vector.

This leaves you with an empty vector, and all elements that were previously inside it are dropped.

Time: O(n)

Binary search a sorted vector for a given element using a comparator function.

Assumes the vector has already been sorted using the same comparator function, eg. by using sort_by.

If the value is found, it returns Ok(index) where index is the index of the element. If the value isn’t found, it returns Err(index) where index is the index at which the element would need to be inserted to maintain sorted order.

Time: O(log n)

Binary search a sorted vector for a given element.

If the value is found, it returns Ok(index) where index is the index of the element. If the value isn’t found, it returns Err(index) where index is the index at which the element would need to be inserted to maintain sorted order.

Time: O(log n)

Binary search a sorted vector for a given element with a key extract function.

Assumes the vector has already been sorted using the same key extract function, eg. by using sort_by_key.

If the value is found, it returns Ok(index) where index is the index of the element. If the value isn’t found, it returns Err(index) where index is the index at which the element would need to be inserted to maintain sorted order.

Time: O(log n)

Construct a vector with a single value.

Examples
let vec = Vector::unit(1337);
assert_eq!(1, vec.len());
assert_eq!(
  vec.get(0),
  Some(&1337)
);

Create a new vector with the value at index index updated.

Panics if the index is out of bounds.

Time: O(log n)

Examples
let mut vec = vector![1, 2, 3];
assert_eq!(vector![1, 5, 3], vec.update(1, 5));

Update the value at index index in a vector.

Returns the previous value at the index.

Panics if the index is out of bounds.

Time: O(log n)

Swap the elements at indices i and j.

Time: O(log n)

Push a value to the front of a vector.

Time: O(1)*

Examples
let mut vec = vector![5, 6, 7];
vec.push_front(4);
assert_eq!(vector![4, 5, 6, 7], vec);

Push a value to the back of a vector.

Time: O(1)*

Examples
let mut vec = vector![1, 2, 3];
vec.push_back(4);
assert_eq!(vector![1, 2, 3, 4], vec);

Remove the first element from a vector and return it.

Time: O(1)*

Examples
let mut vec = vector![1, 2, 3];
assert_eq!(Some(1), vec.pop_front());
assert_eq!(vector![2, 3], vec);

Remove the last element from a vector and return it.

Time: O(1)*

Examples
let mut vec = vector![1, 2, 3];
assert_eq!(Some(3), vec.pop_back());
assert_eq!(vector![1, 2], vec);

Append the vector other to the end of the current vector.

Time: O(log n)

Examples
let mut vec = vector![1, 2, 3];
vec.append(vector![7, 8, 9]);
assert_eq!(vector![1, 2, 3, 7, 8, 9], vec);

Retain only the elements specified by the predicate.

Remove all elements for which the provided function f returns false from the vector.

Time: O(n)

Split a vector at a given index.

Split a vector at a given index, consuming the vector and returning a pair of the left hand side and the right hand side of the split.

Time: O(log n)

Examples
let mut vec = vector![1, 2, 3, 7, 8, 9];
let (left, right) = vec.split_at(3);
assert_eq!(vector![1, 2, 3], left);
assert_eq!(vector![7, 8, 9], right);

Split a vector at a given index.

Split a vector at a given index, leaving the left hand side in the current vector and returning a new vector containing the right hand side.

Time: O(log n)

Examples
let mut left = vector![1, 2, 3, 7, 8, 9];
let right = left.split_off(3);
assert_eq!(vector![1, 2, 3], left);
assert_eq!(vector![7, 8, 9], right);

Construct a vector with count elements removed from the start of the current vector.

Time: O(log n)

Construct a vector of the first count elements from the current vector.

Time: O(log n)

Truncate a vector to the given size.

Discards all elements in the vector beyond the given length.

Panics if the new length is greater than the current length.

Time: O(log n)

Extract a slice from a vector.

Remove the elements from start_index until end_index in the current vector and return the removed slice as a new vector.

Time: O(log n)

Insert an element into a vector.

Insert an element at position index, shifting all elements after it to the right.

Performance Note

While push_front and push_back are heavily optimised operations, insert in the middle of a vector requires a split, a push, and an append. Thus, if you want to insert many elements at the same location, instead of inserting them one by one, you should rather create a new vector containing the elements to insert, split the vector at the insertion point, and append the left hand, the new vector and the right hand in order.

Time: O(log n)

Remove an element from a vector.

Remove the element from position ‘index’, shifting all elements after it to the left, and return the removed element.

Performance Note

While pop_front and pop_back are heavily optimised operations, remove in the middle of a vector requires a split, a pop, and an append. Thus, if you want to remove many elements from the same location, instead of removeing them one by one, it is much better to use slice.

Time: O(log n)

Insert an element into a sorted vector.

Insert an element into a vector in sorted order, assuming the vector is already in sorted order.

Time: O(log n)

Examples
let mut vec = vector![1, 2, 3, 7, 8, 9];
vec.insert_ord(5);
assert_eq!(vector![1, 2, 3, 5, 7, 8, 9], vec);

Sort a vector.

Time: O(n log n)

Examples
let mut vec = vector![3, 2, 5, 4, 1];
vec.sort();
assert_eq!(vector![1, 2, 3, 4, 5], vec);

Sort a vector using a comparator function.

Time: O(n log n)

Examples
let mut vec = vector![3, 2, 5, 4, 1];
vec.sort_by(|left, right| left.cmp(right));
assert_eq!(vector![1, 2, 3, 4, 5], vec);

Verify the internal consistency of a vector.

This method walks the RRB tree making up the current Vector (if it has one) and verifies that all the invariants hold. If something is wrong, it will panic.

This method requires the debug feature flag.

Trait Implementations

Concatenate two vectors.

Time: O(log n)

The resulting type after applying the + operator.

Concatenate two vectors.

Time: O(log n)

The resulting type after applying the + operator.

Return an arbitrary value. Read more

Return an iterator of values that are smaller than itself. Read more

Generate an arbitrary value of Self from the given unstructured data. Read more

Generate an arbitrary value of Self from the entirety of the given unstructured data. Read more

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself. Read more

Clone a vector.

Time: O(1), or O(n) with a very small, bounded n for an inline vector.

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Deserialize this value from the given Serde deserializer. Read more

Add values to the end of a vector by consuming an iterator.

Time: O(n)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

Converts to this type from the input type.

Create a vector from a std::vec::Vec.

Time: O(n)

Converts to this type from the input type.

Converts to this type from the input type.

Create a vector from a std::vec::Vec.

Time: O(n)

Converts to this type from the input type.

Create a vector from an iterator.

Time: O(n)

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

Get a reference to the value at index index in the vector.

Time: O(log n)

The returned type after indexing.

Get a mutable reference to the value at index index in the vector.

Time: O(log n)

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of item that the parallel iterator will produce. This will typically be an &'data T reference type. Read more

The type of the parallel iterator that will be returned.

Converts self into a parallel iterator. Read more

The type of item that will be produced; this is typically an &'data mut T reference. Read more

The type of iterator that will be created.

Creates the parallel iterator from self. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Serialize this value into the given Serde serializer. Read more

Method which takes an iterator and generates Self from the elements by “summing up” the items. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.