Struct corundum::vec::Vec

pub struct Vec<T: PSafe, A: MemPool> { /* fields omitted */ }

A contiguous growable persistent array type, written Vec<T> but pronounced ‘vector’.

PVec is an alias name in the pool module for Vec.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::new();
    vec.push(1, j);
    vec.push(2, j);

    assert_eq!(vec.len(), 2);
    assert_eq!(vec[0], 1);

    assert_eq!(vec.pop(), Some(2));
    assert_eq!(vec.len(), 1);

    vec.extend_from_slice(&[1, 2, 3], j);

    for x in vec.as_slice() {
        println!("{}", x);
    }
    assert_eq!(vec, [1, 1, 2, 3]);

}).unwrap();

Implementations

impl<T: PSafe, A: MemPool> Vec<T, A>

pub const fn new() -> Self

Creates an empty vector with zero capacity for the pool of the give Journal

pub fn from_slice(x: &[T], journal: &Journal<A>) -> Self

Creates an empty vector and places x into it

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2], j);

    assert_eq!(vec.len(), 2);
    assert_eq!(vec[0], 1);

    assert_eq!(vec.pop(), Some(2));
    assert_eq!(vec.len(), 1);

    vec.extend_from_slice(&[1, 2, 3], j);

    for x in &*vec {
        println!("{}", x);
    }

    assert_eq!(vec, [1, 1, 2, 3]);
}).unwrap();

pub fn with_capacity(cap: usize, j: &Journal<A>) -> Self

Creates an empty Vec with the specified capacity

The vector will be able to hold exactly capacity elements without reallocating. If capacity is 0, the vector will not allocate.

It is important to note that although the returned vector has the capacity specified, the vector will have a zero length. For an explanation of the difference between length and capacity, see [Capacity and reallocation].

Examples

Heap::transaction(|j| {
    let mut vec = Vec::with_capacity(10, j);

    // The vector contains no items, even though it has capacity for more
    assert_eq!(vec.len(), 0);

    // These are all done without reallocating...
    for i in 0..10 {
        vec.push(i, j);
    }

    // ...but this may make the vector reallocate
    vec.push(11, j);
}).unwrap();

pub unsafe fn from_raw_parts(
    ptr: *mut T,
    length: usize,
    capacity: usize
) -> Self

Creates a PVec<T> directly from the raw components of another vector.

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

• ptr needs to have been previously allocated via String/Vec<T> (at least, it’s highly likely to be incorrect if it wasn’t).
• ptr should point to the same pool
• T needs to have the same size as what ptr was allocated with.
• length needs to be less than or equal to capacity.
• capacity needs to be the capacity that the pointer was allocated with.

The ownership of ptr is effectively transferred to the PVec<T> which may then deallocate, reallocate or change the contents of memory pointed to by the pointer at will. Ensure that nothing else uses the pointer after calling this function.

Examples

use std::ptr;
use std::mem;
use corundum::alloc::heap::Heap;
use corundum::vec::Vec as PVec;

let v = vec![1, 2, 3];

// Prevent running `v`'s destructor so we are in complete control
// of the allocation.
let mut v = mem::ManuallyDrop::new(v);

// Pull out the various important pieces of information about `v`
let p = v.as_mut_ptr();
let len = v.len();
let cap = v.capacity();

unsafe {
    // Overwrite memory with 4, 5, 6
    for i in 0..len as isize {
        ptr::write(p.offset(i), 4 + i);
    }

    // Put everything back together into a Vec
    let rebuilt = PVec::<isize, Heap>::from_raw_parts(p, len, cap);
    assert_eq!(rebuilt, [4, 5, 6]);
}

pub const fn empty() -> Self

Creates an empty vector with zero capacity

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

Examples

Heap::transaction(|j| {
    let mut v = Vec::new();
    assert!(v.is_empty());

    v.push(1, j);
    assert!(!v.is_empty());
}).unwrap();

pub fn split_off(&mut self, at: usize, j: &Journal<A>) -> Self

Splits the collection into two at the given index.

Returns a newly allocated vector containing the elements in the range [at, len). After the call, the original vector will be left containing the elements [0, at) with its previous capacity unchanged.

Panics

Panics if at > len.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1,2,3], j);
    let vec2 = vec.split_off(1, j);
    assert_eq!(vec, [1]);
    assert_eq!(vec2, [2, 3]);
}).unwrap();

pub fn off(&self) -> u64

Returns the offset of the vector in the persistent pool

pub fn capacity(&self) -> usize

Returns the available capacity of the vector in the persistent pool

pub unsafe fn set_len(&mut self, new_len: usize)

Forces the length of the vector to new_len.

This is a low-level operation that maintains none of the normal invariants of the type. Normally changing the length of a vector is done using one of the safe operations instead, such as truncate, resize, push, or clear.

Safety

• new_len must be less than or equal to capacity().
• The elements at old_len..new_len must be initialized.

pub fn len(&self) -> usize

Returns the length of the vector

pub fn as_slice(&self) -> &[T]

Consumes the vector and converts it into a slice

pub fn as_slice_mut(&mut self, j: &Journal<A>) -> &mut [T]

Consumes the vector and converts it into a slice. Since we should create a log of the context, this function is transactional

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1,2,3], j);
    let s = vec.as_slice_mut(j);
    s[1] = 0;
    assert_eq!(s,   [1, 0, 3]);
    assert_eq!(vec, [1, 0, 3]);
}).unwrap();

pub fn extend_from_slice(&mut self, other: &[T], j: &Journal<A>)

Copy all the elements of other into Self

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    let mut other = vec![4, 5, 6];
    vec.extend_from_slice(&other, j);
    assert_eq!(vec.as_slice(), [1, 2, 3, 4, 5, 6]);
}).unwrap();

pub fn shrink_to(&mut self, new_cap: usize, j: &Journal<A>)

pub fn shrink_to_fit(&mut self, j: &Journal<A>)

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

ExamplesSlice

Heap::transaction(|j| {
    let mut vec = Vec::with_capacity(10, j);
    vec.extend_from_slice(&[1, 2, 3], j);
    assert_eq!(vec.capacity(), 10);
    vec.shrink_to_fit(j);
    assert!(vec.capacity() >= 3);
}).unwrap();

pub fn reserve(&mut self, additional: usize, j: &Journal<A>)

Copy all the elements of other into Self

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    let mut other = vec![4, 5, 6];
    vec.extend_from_slice(&other, j);
    assert_eq!(vec.as_slice(), [1, 2, 3, 4, 5, 6]);
}).unwrap();

pub fn truncate(&mut self, len: usize)

Shortens the vector, keeping the first len elements and dropping the rest.

If len is greater than the vector’s current length, this has no effect.

Note that this method has no effect on the capacity. To shorten the capacity too, use shrink_to or shrink_to_fit.

Examples

Truncating a five element vector to three elements, then truncating it to two:

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3, 4, 5], j);

    vec.truncate(3);
    assert_eq!(vec, [1, 2, 3]);
    assert_eq!(vec.capacity(), 5); // No effect on capacity

    vec.truncate(2);
    assert_eq!(vec.as_slice(), [1, 2]);
    assert_eq!(vec.capacity(), 5); // Capacity is shrunk to 2
}).unwrap();

No truncation occurs when len is greater than the vector’s current length:

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    vec.truncate(8);
    assert_eq!(vec, [1, 2, 3]);
}).unwrap();

Truncating when len == 0 is equivalent to calling the clear method.

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    vec.truncate(0);
    assert_eq!(vec, []);
}).unwrap();

pub fn swap_remove(&mut self, index: usize) -> T

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Panics

Panics if index is out of bounds.

Examples

Heap::transaction(|j| {
    let mut v = Vec::from_slice(&[1, 2, 3, 4], j);

    assert_eq!(v.swap_remove(1), 2);
    assert_eq!(v, [1, 4, 3]);

    assert_eq!(v.swap_remove(0), 1);
    assert_eq!(v, [3, 4]);
}).unwrap();

pub fn insert(&mut self, index: usize, element: T, j: &Journal<A>)

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index > len.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    vec.insert(1, 4, j);
    assert_eq!(vec, [1, 4, 2, 3]);
    vec.insert(4, 5, j);
    assert_eq!(vec, [1, 4, 2, 3, 5]);
}).unwrap();

pub fn remove(&mut self, index: usize) -> T

Removes and returns the element at position index within the vector, shifting all elements after it to the left.

Panics

Panics if index is out of bounds.

Examples

Heap::transaction(|j| {
    let mut v = Vec::from_slice(&[1, 2, 3], j);
    assert_eq!(v.remove(1), 2);
    assert_eq!(v, [1, 3]);
}).unwrap();

pub fn retain<F>(&mut self, f: F) where
    F: FnMut(&T) -> bool, 

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&e) returns false. This method operates in place, visiting each element exactly once in the original order, and preserves the order of the retained elements.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3, 4], j);
    vec.retain(|&x| x % 2 == 0);
    assert_eq!(vec, [2, 4]);
}).unwrap();

The exact order may be useful for tracking external state, like an index.

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3, 4, 5], j);
    let keep = [false, true, true, false, true];
    let mut i = 0;
    vec.retain(|_| (keep[i], i += 1).0);
    assert_eq!(vec, [2, 3, 5]);
}).unwrap();

pub fn push(&mut self, value: T, j: &Journal<A>)

Heap::transaction(|j| { Heap::transaction(|j| { Appends an element to the back of a collection.

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2], j);
    vec.push(3, j);
    assert_eq!(vec, [1, 2, 3]);
}).unwrap();

pub fn pop(&mut self) -> Option<T>

Removes the last element from a vector and returns it, or None if it is empty.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    assert_eq!(vec.pop(), Some(3));
    assert_eq!(vec, [1, 2]);
}).unwrap();

pub fn append(&mut self, other: &mut Self, j: &Journal<A>)

Moves all the elements of other into Self, leaving other empty.

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

Heap::transaction(|j| {
    let mut vec = Vec::from_slice(&[1, 2, 3], j);
    let mut vec2 = Vec::from_slice(&[4, 5, 6], j);
    vec.append(&mut vec2, j);
    assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
    assert_eq!(vec2, []);
}).unwrap();

pub fn clear(&mut self)

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

Examples

Heap::transaction(|j| {
    let mut v = Vec::from_slice(&[1, 2, 3], j);
    v.clear();
    assert!(v.is_empty());
}).unwrap();

pub fn cast<U, F: Fn(&T) -> U>(&self, f: F) -> Vec<U>

impl<A: MemPool> Vec<u8, A>

pub fn to_str(&self) -> &str

Trait Implementations

impl<T: PSafe, A: MemPool> AsRef<[T]> for Vec<T, A>

fn as_ref(&self) -> &[T]

Performs the conversion.

impl<T: PSafe, A: MemPool> AsRef<Vec<T, A>> for Vec<T, A>

fn as_ref(&self) -> &Vec<T, A>

Performs the conversion.

impl<T: PSafe + Debug, A: MemPool> Debug for Vec<T, A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T: PSafe, A: MemPool> Default for Vec<T, A>

fn default() -> Self

Returns the “default value” for a type.

impl<T: PSafe, A: MemPool> Deref for Vec<T, A>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<T: PSafe + Display, A: MemPool> Display for Vec<T, A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T: PSafe, A: MemPool> Drop for Vec<T, A>

fn drop(&mut self)

Executes the destructor for this type.

impl<A: MemPool> From<String<A>> for Vec<u8, A>

fn from(string: String<A>) -> Vec<u8, A>

Converts the given String to a vector Vec that holds values of type u8.

Examples

Basic usage:

Heap::transaction(|j| {
    let s1 = String::<Heap>::pfrom("hello world", j);
    let v1 = Vec::from(s1);

    for b in v1.as_slice() {
        println!("{}", b);
    }
}).unwrap();

impl<A: MemPool, T: PSafe, I: SliceIndex<[T]>> Index<I> for Vec<T, A>

type Output = I::Output

The returned type after indexing.

fn index(&self, index: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: PSafe, A: MemPool> IntoIterator for Vec<T, A>

implement the IntoIterator trait for a consuming iterator. Iteration will consume the Words structure

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIteratorHelper<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T: PSafe, A: MemPool> IntoIterator for &'a Vec<T, A>

implement the IntoIterator trait for a non-consuming iterator. Iteration will borrow the Words structure

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = IterHelper<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<A: MemPool, T: PSafe + Ord> Ord for Vec<T, A>

Implements ordering of vectors, lexicographically.

fn cmp(&self, other: &Vec<T, A>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<A: MemPool, T: PSafe + PClone<A>> PClone<A> for Vec<T, A>

fn pclone(&self, j: &Journal<A>) -> Self

fn pclone_from(&mut self, source: &Self, journal: &Journal<A>)

Performs copy-assignment from source.

impl<T: Clone + PSafe, A: MemPool> PFrom<&'_ [T], A> for Vec<T, A>

fn pfrom(s: &[T], j: &Journal<A>) -> Vec<T, A>

impl<T: Clone + PSafe, A: MemPool> PFrom<&'_ mut [T], A> for Vec<T, A>

fn pfrom(s: &mut [T], j: &Journal<A>) -> Vec<T, A>

impl<A: MemPool> PFrom<&'_ str, A> for Vec<u8, A>

fn pfrom(s: &str, j: &Journal<A>) -> Vec<u8, A>

impl<T: PSafe, A: MemPool> PFrom<Box<[T], Global>, A> for Vec<T, A>

fn pfrom(s: Box<[T]>, j: &Journal<A>) -> Vec<T, A>

impl<T: PSafe, U: PSafe, A: MemPool, const N: usize> PartialEq<&'_ [U; N]> for Vec<T, A> where
    T: PartialEq<U>, 

fn eq(&self, other: &&[U; N]) -> bool

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

fn ne(&self, other: &&[U; N]) -> bool

This method tests for !=.

impl<T: PSafe, U: PSafe, A: MemPool> PartialEq<&'_ [U]> for Vec<T, A> where
    T: PartialEq<U>, 

fn eq(&self, other: &&[U]) -> bool

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

fn ne(&self, other: &&[U]) -> bool

This method tests for !=.

impl<T: PSafe, U: PSafe, A: MemPool> PartialEq<&'_ mut [U]> for Vec<T, A> where
    T: PartialEq<U>, 

fn eq(&self, other: &&mut [U]) -> bool

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

fn ne(&self, other: &&mut [U]) -> bool

This method tests for !=.

impl<T: PSafe, U: PSafe, A: MemPool, const N: usize> PartialEq<[U; N]> for Vec<T, A> where
    T: PartialEq<U>, 

fn eq(&self, other: &[U; N]) -> bool

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

fn ne(&self, other: &[U; N]) -> bool

This method tests for !=.

impl<T: PSafe, U: PSafe, A: MemPool> PartialEq<Vec<U, A>> for Vec<T, A> where
    T: PartialEq<U>, 

fn eq(&self, other: &Vec<U, A>) -> bool

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

fn ne(&self, other: &Vec<U, A>) -> bool

This method tests for !=.

impl<A: MemPool, T: PSafe + PartialOrd> PartialOrd<Vec<T, A>> for Vec<T, A>

Implements comparison of vectors, lexicographically.

fn partial_cmp(&self, other: &Vec<T, A>) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl<T: PSafe, A: MemPool> RootObj<A> for Vec<T, A>

fn init(_: &Journal<A>) -> Self

impl<A: MemPool, T: PSafe + Eq> Eq for Vec<T, A>

impl<T: PSafe, A: MemPool> PSafe for Vec<T, A>

impl<T, A: MemPool> !Send for Vec<T, A>

impl<T, A: MemPool> !Sync for Vec<T, A>

impl<T, A: MemPool> !VSafe for Vec<T, A>