Struct trees::potted::pot::Pot

pub struct Pot<T> { /* fields omitted */ }

Methods from Deref<Target = Pool<Node<T>>>

pub fn push(&mut self, value: T)

Appends an element to the back of a pool.

Panics

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

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: i32 }}

let mut pool = Pool::new();

pool.push( Foo::from( 0 ));
pool.push( Foo::from( 1 ));
pool.push( Foo::from( 2 ));

assert_eq!( pool.iter().map( |e| e.inner ).collect::<Vec<_>>(), vec![ 0, 1, 2 ]);

pub unsafe fn write(&mut self, index: usize, value: T)

Overwrites a new value into a pool at given index without reading or dropping the old value.

Safety

This operation is marked unsafe because it accepts an index as an offset which acts like a raw pointer.

It does not drop the contents of the existing self[index] element. This is safe, but it could leak allocations or resources, so care must be taken not to overwrite an object that should be dropped.

Additionally, it does not drop value. Semantically, value is moved into self[index].

This is appropriate for initializing uninitialized memory.

Examples

Basic usage:

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::<Foo>::new();

pool.reserve( 3 );

unsafe {
    pool.write( 0, "a".into() );
    pool.write( 2, "c".into() );
    pool.write( 1, "b".into() );
    pool.set_len( 3 );
}

assert_eq!( pool.iter().map( |e| e.inner ).collect::<Vec<_>>(), vec![ "a", "b", "c" ]);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the given Pool. The collection may reserve more space because the increasing size must be multiple of underlying chunk_len(). After calling reserve, capacity will be greater than or equal to self.new_index() + additional. Does nothing if capacity is already sufficient.

Panics

Panics if the new capacity overflows usize.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::<Foo>::new();

pool.reserve( 0 );
assert_eq!( pool.capacity(), 0 );

pool.reserve( 1 );
let cap = pool.capacity();
assert!( cap >= 1 );

pool.reserve( 1 );
assert_eq!( pool.capacity(), cap );

pool.reserve( 1024 );
assert!( pool.capacity() >= 1024 );

pub fn len(&self) -> usize

Returns the number of elements in the pool, also referred to as its ‘length’.

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = pool!( Foo[ "a", "b", "c" ]);
assert_eq!( pool.len(), 3 );

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

Sets the length of a pool.

This will explicitly set the size of the pool, without actually modifying its buffers, so it is up to the caller to ensure that the pool is actually the specified size.

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: char }}

let mut pool = pool!( Foo[ 'r', 'u', 's', 't' ]);

unsafe {
    std::ptr::drop_in_place( &mut pool[3] );
    pool.set_len( 3 );
}

assert_eq!( pool.len(), 3 );
assert_eq!( pool.iter().map( |e| e.inner ).collect::<Vec<_>>(), vec!['r', 'u', 's'] );

In this example, there is a memory leak since the memory locations owned by the first Name were not freed prior to the set_len call:

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

static mut COUNT: usize = 0;

struct Name { index: usize, text: String }

impl_indexed!{ Name{ index: usize }}

impl Drop for Name { fn drop( &mut self ) { unsafe{ COUNT += 1; }}}

impl From<&'static str> for Name {
    fn from( s: &'static str ) -> Self {
        Name{ index: <Self as Indexed>::null(), text: s.to_string() }
    }
}

let mut pool = pool!( Name[ "abc", "def", "g" ]);

unsafe {
    std::ptr::drop_in_place( &mut pool[2] );
    std::ptr::drop_in_place( &mut pool[1] );
    pool.set_len( 0 );
}

assert_eq!( unsafe{ COUNT }, 2 );

In this example, the pool gets expanded from zero to four items without any memory allocations occurring, resulting in pool values of unallocated memory:

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::<Foo>::new();
unsafe { pool.set_len( 3 ); }

pub fn capacity(&self) -> usize

Returns the number of elements the vector can hold without more allocating.

Note: the purpose of this method is not to avoid reallocation, which could not happen at all, but to grow the buffer for next incomming write()s.

pub fn non_null(&self) -> NonNull<Pool<T>>

Returns the pool’s NonNull pointer.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: i32 }}

let mut pool = Pool::<Foo>::new();
let p = pool.non_null();

assert_eq!( p, std::ptr::NonNull::new( Box::into_raw( pool )).unwrap() );

pub fn new_index(&self) -> usize

Returns the expected index for the next new element to be push()ed in.

pub fn is_empty(&self) -> bool

Returns true if the pool contains no elements.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = Pool::new();
assert!( pool.is_empty() );

pool.push( Foo::from( "foo" ));
assert!( !pool.is_empty() );

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over the pool.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: &'static str }}

let mut pool = pool!( Foo[ "abc", "def", "g" ]);
let mut iter = pool.iter();

assert_eq!( iter.next().unwrap().inner, "abc" );
assert_eq!( iter.next().unwrap().inner, "def" );
assert_eq!( iter.next().unwrap().inner, "g"   );
assert!( iter.next().is_none() );

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns an iterator that allows modifying each value.

Examples

#[macro_use] extern crate indexed;
use indexed::{Indexed,Pool};

extrusive_indexed!{ Foo{ inner: i32 }}

let mut pool = pool!( Foo[ 0, 1, 2 ]);

pool.iter_mut().for_each( |elem| { elem.inner += 10; });

assert_eq!( pool.iter().map( |e| e.inner ).collect::<Vec<_>>(), vec![ 10, 11, 12 ]);

pub unsafe fn get_unchecked(&self, index: usize) -> &T

Returns a shared reference to the output at indexed location, without performing any bounds checking.

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

Returns a mutable reference to the output at indexed location, without performing any bounds checking.

Trait Implementations

impl<T> Clone for Pot<T>

fn clone(&self) -> Self

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Copy for Pot<T>

impl<T: Debug> Debug for Pot<T>

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

Formats the value using the given formatter.

impl<T> Deref for Pot<T>

type Target = Pool<Node<T>>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Pot<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.