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
sourceimpl<T> Arena<T>
impl<T> Arena<T>
sourcepub fn with_capacity(n: usize) -> Arena<T>
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);
sourcepub fn len(&self) -> usize
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);
sourcepub fn alloc(&self, value: T) -> &mut T
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);
sourcepub fn alloc_extend<I>(&self, iterable: I) -> &mut [T]ⓘNotable traits for &[u8]impl<'_> Read for &[u8]impl<'_> Write for &mut [u8]
where
I: IntoIterator<Item = T>,
pub fn alloc_extend<I>(&self, iterable: I) -> &mut [T]ⓘNotable traits for &[u8]impl<'_> Read for &[u8]impl<'_> Write for &mut [u8]
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']);
sourcepub unsafe fn alloc_uninitialized(&self, num: usize) -> *mut [T]
pub unsafe fn alloc_uninitialized(&self, num: usize) -> *mut [T]
Allocates space for a given number of values, but doesn’t initialize it.
Unsafety and Undefined Behavior
The same caveats that apply to
std::mem::uninitialized
apply here:
This is incredibly dangerous and should not be done lightly. Deeply consider initializing your memory with a default value instead.
In particular, it is easy to trigger undefined behavior by allocating
uninitialized values, failing to properly initialize them, and then the
Arena
will attempt to drop them when it is dropped. Initializing an
uninitialized value is trickier than it might seem: a normal assignment
to a field will attempt to drop the old, uninitialized value, which
almost certainly also triggers undefined behavior. You must also
consider all the places where your code might “unexpectedly” drop values
earlier than it “should” because of unwinding during panics.
sourcepub fn uninitialized_array(&self) -> *mut [T]
pub fn uninitialized_array(&self) -> *mut [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.
sourcepub fn into_vec(self) -> Vec<T, Global>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
pub fn into_vec(self) -> Vec<T, Global>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
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"]);
sourcepub fn iter_mut(&mut self) -> IterMut<'_, T>
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;
Trait Implementations
Auto Trait Implementations
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
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more