comrak

Struct Arena

Source
pub struct Arena<T> { /* private fields */ }
Expand description

An arena of objects of type T.

§Example

use typed_arena::Arena;

struct Monster {
    level: u32,
}

let monsters = Arena::new();

let vegeta = monsters.alloc(Monster { level: 9001 });
assert!(vegeta.level > 9000);

Implementations§

Source§

impl<T> Arena<T>

Source

pub fn new() -> Arena<T>

Construct a new arena.

§Example
use typed_arena::Arena;

let arena = Arena::new();
Source

pub 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);
Source

pub fn len(&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);
Source

pub fn alloc(&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);
Source

pub fn alloc_extend<I>(&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']);
Source

pub unsafe fn alloc_uninitialized(&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.

§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 with 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()]);
}
Source

pub fn reserve_extend(&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. It also allows somewhat safer use pattern of 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.

Source

pub fn uninitialized_array(&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, or 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.

Source

pub fn into_vec(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"]);
Source

pub fn iter_mut(&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;
Source§

impl Arena<u8>

Source

pub fn alloc_str(&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);

Trait Implementations§

Source§

impl<T> Default for Arena<T>

Source§

fn default() -> Arena<T>

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

Auto Trait Implementations§

§

impl<T> !Freeze for Arena<T>

§

impl<T> !RefUnwindSafe for Arena<T>

§

impl<T> Send for Arena<T>
where T: Send,

§

impl<T> !Sync for Arena<T>

§

impl<T> Unpin for Arena<T>
where T: Unpin,

§

impl<T> UnwindSafe for Arena<T>
where T: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

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

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

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

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.