impl Arena<u8>

fn alloc_str(self: &Self, s: &str) -> &mut str

Allocates a string slice and returns a mutable reference to it.

This is on Arena<u8>, because string slices use byte slices ([u8]) as their backing storage.

Example

use typed_arena::Arena;

let arena: Arena<u8> = Arena::new();
let hello = arena.alloc_str("Hello world");
assert_eq!("Hello world", hello);

impl<T> Arena<T>

fn new() -> Arena<T>

Construct a new arena.

Example

use typed_arena::Arena;

let arena = Arena::new();
# arena.alloc(1);

fn with_capacity(n: usize) -> Arena<T>

Construct a new arena with capacity for n values pre-allocated.

Example

use typed_arena::Arena;

let arena = Arena::with_capacity(1337);
# arena.alloc(1);

fn len(self: &Self) -> usize

Return the size of the arena

This is useful for using the size of previous typed arenas to build new typed arenas with large enough spaces.

Example

 use typed_arena::Arena;

 let arena = Arena::with_capacity(0);
 let a = arena.alloc(1);
 let b = arena.alloc(2);

 assert_eq!(arena.len(), 2);

fn alloc(self: &Self, value: T) -> &mut T

Allocates a value in the arena, and returns a mutable reference to that value.

Example

use typed_arena::Arena;

let arena = Arena::new();
let x = arena.alloc(42);
assert_eq!(*x, 42);

fn alloc_extend<I>(self: &Self, iterable: I) -> &mut [T]
where
    I: IntoIterator<Item = T>

Uses the contents of an iterator to allocate values in the arena. Returns a mutable slice that contains these values.

Example

use typed_arena::Arena;

let arena = Arena::new();
let abc = arena.alloc_extend("abcdefg".chars().take(3));
assert_eq!(abc, ['a', 'b', 'c']);

unsafe fn alloc_uninitialized(self: &Self, num: usize) -> &mut [MaybeUninit<T>]

Allocates space for a given number of values, but doesn't initialize it.

Safety

After calling this method, the arena considers the elements initialized. If you fail to initialize them (which includes because of panicking during the initialization), the arena will run destructors on the uninitialized memory. Therefore, you must initialize them.

Considering how easy it is to cause undefined behaviour using this, you're advised to prefer the other (safe) methods, like [alloc_extend][Arena::alloc_extend].

Example

use std::mem::{self, MaybeUninit};
use std::ptr;
use typed_arena::Arena;

// Transmute from MaybeUninit slice to slice of initialized T.
// It is a separate function to preserve the lifetime of the reference.
unsafe fn transmute_uninit<A>(r: &mut [MaybeUninit<A>]) -> &mut [A] {
    mem::transmute(r)
}

let arena: Arena<bool> = Arena::new();
let slice: &mut [bool];
unsafe {
    let uninitialized = arena.alloc_uninitialized(10);
    for elem in uninitialized.iter_mut() {
        ptr::write(elem.as_mut_ptr(), true);
    }
    slice = transmute_uninit(uninitialized);
}

Alternative allocation pattern

To avoid the problem of dropping assumed to be initialized elements on panic, it is also possible to combine the [reserve_extend][Arena::reserve_extend] with [uninitialized_array][Arena::uninitialized_array], initialize the elements and confirm them by this method. In such case, when there's a panic during initialization, the already initialized elements would leak but it wouldn't cause UB.

use std::mem::{self, MaybeUninit};
use std::ptr;
use typed_arena::Arena;

unsafe fn transmute_uninit<A>(r: &mut [MaybeUninit<A>]) -> &mut [A] {
    mem::transmute(r)
}

const COUNT: usize = 2;

let arena: Arena<String> = Arena::new();

arena.reserve_extend(COUNT);
let slice: &mut [String];
unsafe {
    // Perform initialization before we claim the memory.
    let uninitialized = arena.uninitialized_array();
    assert!((*uninitialized).len() >= COUNT); // Ensured by the reserve_extend
    for elem in &mut (*uninitialized)[..COUNT] {
        ptr::write(elem.as_mut_ptr(), "Hello".to_owned());
    }
    let addr = (*uninitialized).as_ptr() as usize;

    // The alloc_uninitialized returns the same memory, but "confirms" its allocation.
    slice = transmute_uninit(arena.alloc_uninitialized(COUNT));
    assert_eq!(addr, slice.as_ptr() as usize);
    assert_eq!(slice, &["Hello".to_owned(), "Hello".to_owned()]);
}

fn reserve_extend(self: &Self, num: usize)

Makes sure there's enough continuous space for at least num elements.

This may save some work if called before [alloc_extend][Arena::alloc_extend]. It also allows somewhat safer use pattern of [alloc_uninitialized][Arena::alloc_uninitialized]. On the other hand this might waste up to n - 1 elements of space. In case new allocation is needed, the unused ones in current chunk are never used.

fn uninitialized_array(self: &Self) -> *mut [MaybeUninit<T>]

Returns unused space.

This unused space is still not considered "allocated". Therefore, it won't be dropped unless there are further calls to alloc, [alloc_uninitialized][Arena::alloc_uninitialized], or [alloc_extend][Arena::alloc_extend] which is why the method is safe.

It returns a raw pointer to avoid creating multiple mutable references to the same place. It is up to the caller not to dereference it after any of the alloc_ methods are called.

fn into_vec(self: Self) -> Vec<T>

Convert this Arena into a Vec<T>.

Items in the resulting Vec<T> appear in the order that they were allocated in.

Example

use typed_arena::Arena;

let arena = Arena::new();

arena.alloc("a");
arena.alloc("b");
arena.alloc("c");

let easy_as_123 = arena.into_vec();

assert_eq!(easy_as_123, vec!["a", "b", "c"]);

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

Returns an iterator that allows modifying each value.

Items are yielded in the order that they were allocated.

Example

use typed_arena::Arena;

#[derive(Debug, PartialEq, Eq)]
struct Point { x: i32, y: i32 };

let mut arena = Arena::new();

arena.alloc(Point { x: 0, y: 0 });
arena.alloc(Point { x: 1, y: 1 });

for point in arena.iter_mut() {
    point.x += 10;
}

let points = arena.into_vec();

assert_eq!(points, vec![Point { x: 10, y: 0 }, Point { x: 11, y: 1 }]);

Immutable Iteration

Note that there is no corresponding iter method. Access to the arena's contents requries mutable access to the arena itself.

use typed_arena::Arena;

let mut arena = Arena::new();
let x = arena.alloc(1);

// borrow error!
for i in arena.iter_mut() {
    println!("i: {}", i);
}

// borrow error!
*x = 2;

impl<T> Any for Arena<T>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Arena<T>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Arena<T>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> Default for Arena<T>

fn default() -> Self

impl<T> Freeze for Arena<T>

impl<T> From for Arena<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> RefUnwindSafe for Arena<T>

impl<T> Send for Arena<T>

impl<T> Sync for Arena<T>

impl<T> Unpin for Arena<T>

impl<T> UnsafeUnpin for Arena<T>

impl<T> UnwindSafe for Arena<T>

impl<T, U> Into for Arena<T>

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for Arena<T>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Arena<T>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>