Struct BumpScope

pub struct BumpScope<'a, A = Global, const MIN_ALIGN: usize = 1, const UP: bool = true, const GUARANTEED_ALLOCATED: bool = true> { /* private fields */ }

A bump allocation scope.

A BumpScope’s allocations are live for 'a, which is the lifetime of its associated BumpScopeGuard(Root) or scoped closure.

BumpScope has the same allocation api as Bump. The only thing that is missing is reset and methods that consume the Bump. For a method overview and examples, have a look at the Bump docs.

This type is provided as a parameter to the closure of Bump::scoped, BumpScope::scoped or created by BumpScopeGuard::scope and BumpScopeGuardRoot::scope. A Bump can also turned into a BumpScope using as_scope, as_mut_scope or into.

Implementations

impl<'a, A, const MIN_ALIGN: usize, const UP: bool> BumpScope<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<true>,

These functions are only available if the BumpScope is guaranteed allocated.

pub fn scoped<R>( &mut self, f: impl FnOnce(BumpScope<'_, A, MIN_ALIGN, UP>) -> R, ) -> R

Calls f with a new child scope.

Examples

let mut bump: Bump = Bump::new();

bump.scoped(|bump| {
    bump.alloc_str("Hello world!");
    assert_eq!(bump.stats().allocated(), 12);
});

assert_eq!(bump.stats().allocated(), 0);

pub fn scoped_aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(BumpScope<'_, A, MIN_ALIGN, UP>) -> R, ) -> R

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Calls f with a new child scope of a new minimum alignment.

pub fn scope_guard(&mut self) -> BumpScopeGuard<'_, A, MIN_ALIGN, UP>

Creates a new BumpScopeGuard. This allows for creation of child scopes.

Examples

let mut bump: Bump = Bump::new();

{
    let mut guard = bump.scope_guard();
    let bump = guard.scope();
    bump.alloc_str("Hello world!");
    assert_eq!(bump.stats().allocated(), 12);
}

assert_eq!(bump.stats().allocated(), 0);

pub fn aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(BumpScope<'_, A, NEW_MIN_ALIGN, UP>) -> R, ) -> R

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Calls f with this scope but with a new minimum alignment.

pub fn checkpoint(&self) -> Checkpoint

Creates a checkpoint of the current bump position.

Examples

let checkpoint = bump.checkpoint();

{
    let hello = bump.alloc_str("hello");
    assert_eq!(bump.stats().allocated(), 5);
}

unsafe { bump.reset_to(checkpoint); }
assert_eq!(bump.stats().allocated(), 0);

pub unsafe fn reset_to(&self, checkpoint: Checkpoint)

Resets the bump position to a previously created checkpoint. The memory that has been allocated since then will be reused by future allocations.

Safety

• the checkpoint must have been created by this bump allocator
• the bump allocator must not have been reset since creation of this checkpoint
• there must be no references to allocations made since creation of this checkpoint

impl<'a, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

pub fn stats(&self) -> Stats<'a, GUARANTEED_ALLOCATED>

Returns a type which provides statistics about the memory usage of the bump allocator.

pub fn allocator(&self) -> &A

Returns a reference to the base allocator.

pub fn as_scope(&self) -> &Self

Returns &self as is. This is useful for macros that support both Bump and BumpScope.

pub fn as_mut_scope(&mut self) -> &mut Self

Returns &mut self as is. This is useful for macros that support both Bump and BumpScope.

pub fn into_aligned<const NEW_MIN_ALIGN: usize>( self, ) -> BumpScope<'a, A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Converts this BumpScope into a BumpScope with a new minimum alignment.

This can not decrease the alignment. Trying to decrease alignment will result in a compile error. You can use aligned or scoped_aligned to decrease the alignment.

To decrease alignment we need to ensure that we return to our original alignment. That can only be guaranteed by a function taking a closure like the ones mentioned above.

This mustn't decrease alignment because otherwise you could do this:

let mut bump: Bump<Global, 8, true> = Bump::new();
let mut guard = bump.scope_guard();

{
    let scope = guard.scope().into_aligned::<1>();
    scope.alloc(0u8);
}

{
    let scope = guard.scope();
    // scope is not aligned to `MIN_ALIGN`!!
}

pub fn as_aligned_mut<const NEW_MIN_ALIGN: usize>( &mut self, ) -> &mut BumpScope<'a, A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Mutably borrows BumpScope with a new minimum alignment.

This can not decrease the alignment. Trying to decrease alignment will result in a compile error. You can use aligned or scoped_aligned to decrease the alignment.“

To decrease alignment we need to ensure that we return to our original alignment. That can only be guaranteed by a function taking a closure like the ones mentioned above.

pub fn guaranteed_allocated(self) -> BumpScope<'a, A, MIN_ALIGN, UP>

Converts this BumpScope into a guaranteed allocated BumpScope.

Panics

Panics if the allocation fails.

pub fn try_guaranteed_allocated( self, ) -> Result<BumpScope<'a, A, MIN_ALIGN, UP>, AllocError>

Converts this BumpScope into a guaranteed allocated BumpScope.

Errors

Errors if the allocation fails.

pub fn guaranteed_allocated_ref(&self) -> &BumpScope<'a, A, MIN_ALIGN, UP>

Borrows BumpScope as a guaranteed allocated BumpScope.

Panics

Panics if the allocation fails.

pub fn try_guaranteed_allocated_ref( &self, ) -> Result<&BumpScope<'a, A, MIN_ALIGN, UP>, AllocError>

Borrows BumpScope as a guaranteed allocated BumpScope.

Errors

Errors if the allocation fails.

pub fn guaranteed_allocated_mut( &mut self, ) -> &mut BumpScope<'a, A, MIN_ALIGN, UP>

Mutably borrows BumpScope as a guaranteed allocated BumpScope.

Panics

Panics if the allocation fails.

pub fn try_guaranteed_allocated_mut( &mut self, ) -> Result<&mut BumpScope<'a, A, MIN_ALIGN, UP>, AllocError>

Mutably borrows BumpScope as a guaranteed allocated BumpScope.

Errors

Errors if the allocation fails.

pub fn not_guaranteed_allocated(self) -> BumpScope<'a, A, MIN_ALIGN, UP, false>

Converts this BumpScope into a not guaranteed allocated BumpScope.

pub fn not_guaranteed_allocated_ref( &self, ) -> &BumpScope<'a, A, MIN_ALIGN, UP, false>

Borrows BumpScope as a not guaranteed allocated BumpScope.

Note that it’s not possible to mutably borrow as a not guaranteed allocated bump allocator. That’s because a user could mem::swap it with an actual unallocated bump allocator which in turn would make &mut self unallocated.

pub fn into_raw(self) -> NonNull<()>

Converts this BumpScope into a raw pointer.

pub unsafe fn from_raw(ptr: NonNull<()>) -> Self

Converts the raw pointer that was created with into_raw back into a BumpScope.

Safety

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

• ptr must have been created with Self::into_raw.
• This function must only be called once with this ptr.
• The lifetime must be the original one.
• Nothing must have been allocated since then.

impl<'a, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

pub fn alloc_zeroed<T>(&self) -> BumpBox<'a, T>

where T: FromZeros,

Available on crate feature zerocopy only.

Allocate a zeroed object.

Panics

Panics if the allocation fails.

Examples

let zero = bump.alloc_zeroed::<i32>();
assert_eq!(*zero, 0);

pub fn alloc_zeroed_slice<T>(&self, len: usize) -> BumpBox<'a, [T]>

where T: FromZeros,

Available on crate feature zerocopy only.

Allocate a zeroed object slice.

Panics

Panics if the allocation fails.

Examples

let zeroes = bump.alloc_zeroed_slice::<i32>(3);
assert_eq!(*zeroes, [0; 3]);

pub fn try_alloc_zeroed<T>(&self) -> Result<BumpBox<'a, T>, AllocError>

where T: FromZeros,

Available on crate feature zerocopy only.

Allocate a zeroed object.

Errors

Errors if the allocation fails.

Examples

let zero = bump.try_alloc_zeroed::<i32>()?;
assert_eq!(*zero, 0);

pub fn try_alloc_zeroed_slice<T>( &self, len: usize, ) -> Result<BumpBox<'a, [T]>, AllocError>

where T: FromZeros,

Available on crate feature zerocopy only.

Allocate a zeroed object slice.

Errors

Errors if the allocation fails.

Examples

let zeroes = bump.try_alloc_zeroed_slice::<i32>(3)?;
assert_eq!(*zeroes, [0; 3]);

impl<'a, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

Functions to allocate. Available as fallible or infallible.

pub fn alloc<T>(&self, value: T) -> BumpBox<'a, T>

Allocate an object.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc(123);
assert_eq!(allocated, 123);

pub fn alloc_with<T>(&self, f: impl FnOnce() -> T) -> BumpBox<'a, T>

Pre-allocate space for an object. Once space is allocated f will be called to create the value to be put at that place. In some situations this can help the compiler realize that T can be constructed at the allocated space instead of having to copy it over.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_with(|| 123);
assert_eq!(allocated, 123);

pub fn alloc_default<T: Default>(&self) -> BumpBox<'a, T>

Allocate an object with its default value. This is equivalent to alloc_with(T::default).

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_default::<i32>();
assert_eq!(allocated, 0);

pub fn alloc_slice_copy<T: Copy>(&self, slice: &[T]) -> BumpBox<'a, [T]>

Allocate a slice and Copy elements from an existing slice.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_copy(&[1, 2, 3]);
assert_eq!(allocated, [1, 2, 3]);

pub fn alloc_slice_clone<T: Clone>(&self, slice: &[T]) -> BumpBox<'a, [T]>

Allocate a slice and Clone elements from an existing slice.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_clone(&[String::from("a"), String::from("b")]);
assert_eq!(allocated, [String::from("a"), String::from("b")]);

pub fn alloc_slice_fill<T: Clone>( &self, len: usize, value: T, ) -> BumpBox<'a, [T]>

Allocate a slice and fill it with elements by cloning value.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_fill(3, "ho");
assert_eq!(allocated, ["ho", "ho", "ho"]);

pub fn alloc_slice_fill_with<T>( &self, len: usize, f: impl FnMut() -> T, ) -> BumpBox<'a, [T]>

Allocates a slice by fill it with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d rather Clone a given value, use alloc_slice_fill. If you want to use the Default trait to generate values, you can pass Default::default as the argument.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_fill_with::<i32>(3, Default::default);
assert_eq!(allocated, [0, 0, 0]);

pub fn alloc_str(&self, src: &str) -> BumpBox<'a, str>

Allocate a str.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_str("Hello world!");
assert_eq!(allocated, "Hello world!");

pub fn alloc_fmt(&self, args: Arguments<'_>) -> BumpBox<'a, str>

Allocate a str from format arguments.

If you have a &mut self you can use alloc_fmt_mut instead for better performance.

Panics

Panics if the allocation fails.

Panics if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_fmt(format_args!("{one} + {two} = {}", one + two));

assert_eq!(string, "1 + 2 = 3");

pub fn alloc_fmt_mut(&mut self, args: Arguments<'_>) -> BumpBox<'a, str>

Allocate a str from format arguments.

This function is designed as a performance improvement over alloc_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for its string buffer. As a result, the string buffer rarely needs to grow.

Panics

Panics if the allocation fails.

Panics if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_fmt_mut(format_args!("{one} + {two} = {}", one + two));

assert_eq!(string, "1 + 2 = 3");

pub fn alloc_cstr(&self, src: &CStr) -> &'a CStr

Allocate a CStr.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_cstr(c"Hello world!");
assert_eq!(allocated, c"Hello world!");

pub fn alloc_cstr_from_str(&self, src: &str) -> &'a CStr

Allocate a CStr from a str.

If src contains a '\0' then the CStr will stop there.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_cstr_from_str("Hello world!");
assert_eq!(allocated, c"Hello world!");

let allocated = bump.alloc_cstr_from_str("abc\0def");
assert_eq!(allocated, c"abc");

pub fn alloc_cstr_fmt(&self, args: Arguments<'_>) -> &'a CStr

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop there.

If you have a &mut self you can use alloc_cstr_fmt_mut instead for better performance.

Panics

Panics if the allocation fails.

Panics if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_cstr_fmt(format_args!("{one} + {two} = {}", one + two));
assert_eq!(string, c"1 + 2 = 3");

let one = bump.alloc_cstr_fmt(format_args!("{one}\0{two}"));
assert_eq!(one, c"1");

pub fn alloc_cstr_fmt_mut(&mut self, args: Arguments<'_>) -> &'a CStr

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop there.

This function is designed as a performance improvement over alloc_cstr_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for its string buffer. As a result, the string buffer rarely needs to grow.

Panics

Panics if the allocation fails.

Panics if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_cstr_fmt_mut(format_args!("{one} + {two} = {}", one + two));
assert_eq!(string, c"1 + 2 = 3");

let one = bump.alloc_cstr_fmt_mut(format_args!("{one}\0{two}"));
assert_eq!(one, c"1");

pub fn alloc_iter<T>( &self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'a, [T]>

Allocate elements of an iterator into a slice.

If you have an impl ExactSizeIterator then you can use alloc_iter_exact instead for better performance.

If iter is not an ExactSizeIterator but you have a &mut self you can still get somewhat better performance by using alloc_iter_mut.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);

pub fn alloc_iter_exact<T, I>( &self, iter: impl IntoIterator<Item = T, IntoIter = I>, ) -> BumpBox<'a, [T]>

where I: ExactSizeIterator<Item = T>,

Allocate elements of an ExactSizeIterator into a slice.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter_exact([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);

pub fn alloc_iter_mut<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'a, [T]>

Allocate elements of an iterator into a slice.

This function is designed as a performance improvement over alloc_iter. By taking self as &mut, it can use the entire remaining chunk space as the capacity for its vector. As a result, the vector rarely needs to grow.

When bumping downwards, prefer alloc_iter_mut_rev instead.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter_mut([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);

pub fn alloc_iter_mut_rev<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'a, [T]>

Allocate elements of an iterator into a slice in reverse order.

Compared to alloc_iter_mut this function is more performant for downwards bumping allocators as the allocation for the vector can be shrunk in place without any ptr::copy.

The reverse is true when upwards allocating. In that case it’s better to use alloc_iter_mut to prevent the ptr::copy.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter_mut_rev([1, 2, 3]);
assert_eq!(slice, [3, 2, 1]);

pub fn alloc_uninit<T>(&self) -> BumpBox<'a, MaybeUninit<T>>

Allocate an unitialized object.

You can safely initialize the object with init or unsafely with assume_init.

Panics

Panics if the allocation fails.

Examples

Safely:

let five = bump.alloc_uninit();

let five = five.init(5);

assert_eq!(*five, 5)

Unsafely:

let mut five = bump.alloc_uninit();

let five = unsafe {
    five.write(5);
    five.assume_init()
};

assert_eq!(*five, 5)

pub fn alloc_uninit_slice<T>(&self, len: usize) -> BumpBox<'a, [MaybeUninit<T>]>

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone or unsafely with assume_init.

Panics

Panics if the allocation fails.

Examples

Safely:

let values = bump.alloc_uninit_slice(3);

let values = values.init_copy(&[1, 2, 3]);

assert_eq!(values, [1, 2, 3])

Unsafely:

let mut values = bump.alloc_uninit_slice(3);

let values = unsafe {
    values[0].write(1);
    values[1].write(2);
    values[2].write(3);

    values.assume_init()
};

assert_eq!(values, [1, 2, 3]);

pub fn alloc_uninit_slice_for<T>( &self, slice: &[T], ) -> BumpBox<'a, [MaybeUninit<T>]>

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone or unsafely with assume_init.

This is just like alloc_uninit_slice but uses a slice to provide the len. This avoids a check for a valid layout. The elements of slice are irrelevant.

Panics

Panics if the allocation fails.

Examples

let slice = &[1, 2, 3];
let other_slice = bump.alloc_uninit_slice_for(slice);
assert_eq!(other_slice.len(), 3);

pub fn alloc_fixed_vec<T>(&self, capacity: usize) -> FixedBumpVec<'a, T>

Allocate a FixedBumpVec with the given capacity.

Panics

Panics if the allocation fails.

Examples

let mut values = bump.alloc_fixed_vec(3);
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3])

pub fn alloc_fixed_string(&self, capacity: usize) -> FixedBumpString<'a>

Allocate a FixedBumpString with the given capacity in bytes.

Panics

Panics if the allocation fails.

Examples

let mut string = bump.alloc_fixed_string(12);
string.push_str("Hello");
string.push_str(" world!");
assert_eq!(string, "Hello world!");

pub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>

Allocates memory as described by the given Layout.

Panics

Panics if the allocation fails.

pub fn reserve_bytes(&self, additional: usize)

Reserves capacity for at least additional more bytes to be bump allocated. The bump allocator may reserve more space to avoid frequent reallocations. After calling reserve_bytes, self.stats().remaining() will be greater than or equal to additional. Does nothing if the capacity is already sufficient.

Panics

Panics if the allocation fails.

Examples

let bump: Bump = Bump::new();
assert!(bump.stats().capacity() < 4096);

bump.reserve_bytes(4096);
assert!(bump.stats().capacity() >= 4096);

pub fn try_alloc<T>(&self, value: T) -> Result<BumpBox<'a, T>, AllocError>

Allocate an object.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc(123)?;
assert_eq!(allocated, 123);

pub fn try_alloc_with<T>( &self, f: impl FnOnce() -> T, ) -> Result<BumpBox<'a, T>, AllocError>

Pre-allocate space for an object. Once space is allocated f will be called to create the value to be put at that place. In some situations this can help the compiler realize that T can be constructed at the allocated space instead of having to copy it over.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_with(|| 123)?;
assert_eq!(allocated, 123);

pub fn try_alloc_default<T: Default>( &self, ) -> Result<BumpBox<'a, T>, AllocError>

Allocate an object with its default value. This is equivalent to try_alloc_with(T::default).

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_default()?;
assert_eq!(allocated, 0);

pub fn try_alloc_slice_copy<T: Copy>( &self, slice: &[T], ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocate a slice and Copy elements from an existing slice.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.alloc_slice_copy(&[1, 2, 3]);
assert_eq!(allocated, [1, 2, 3]);

pub fn try_alloc_slice_clone<T: Clone>( &self, slice: &[T], ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocate a slice and Clone elements from an existing slice.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_clone(&[String::from("a"), String::from("b")])?;
assert_eq!(allocated, [String::from("a"), String::from("b")]);

pub fn try_alloc_slice_fill<T: Clone>( &self, len: usize, value: T, ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocate a slice and fill it with elements by cloning value.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_fill(3, "ho")?;
assert_eq!(allocated, ["ho", "ho", "ho"]);

pub fn try_alloc_slice_fill_with<T>( &self, len: usize, f: impl FnMut() -> T, ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocates a slice by fill it with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d rather Clone a given value, use try_alloc_slice_fill. If you want to use the Default trait to generate values, you can pass Default::default as the argument.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_fill_with::<i32>(3, Default::default)?;
assert_eq!(allocated, [0, 0, 0]);

pub fn try_alloc_str(&self, src: &str) -> Result<BumpBox<'a, str>, AllocError>

Allocate a str.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_str("Hello world!")?;
assert_eq!(allocated, "Hello world!");

pub fn try_alloc_fmt( &self, args: Arguments<'_>, ) -> Result<BumpBox<'a, str>, AllocError>

Allocate a str from format arguments.

If you have a &mut self you can use try_alloc_fmt_mut instead for better performance.

Errors

Errors if the allocation fails.

Errors if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_fmt(format_args!("{one} + {two} = {}", one + two))?;

assert_eq!(string, "1 + 2 = 3");

pub fn try_alloc_fmt_mut( &mut self, args: Arguments<'_>, ) -> Result<BumpBox<'a, str>, AllocError>

Allocate a str from format arguments.

This function is designed as a performance improvement over try_alloc_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for its string buffer. As a result, the string buffer rarely needs to grow.

Errors

Errors if the allocation fails.

Errors if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_fmt_mut(format_args!("{one} + {two} = {}", one + two))?;

assert_eq!(string, "1 + 2 = 3");

pub fn try_alloc_cstr(&self, src: &CStr) -> Result<&'a CStr, AllocError>

Allocate a CStr.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_cstr(c"Hello world!")?;
assert_eq!(allocated, c"Hello world!");

pub fn try_alloc_cstr_from_str(&self, src: &str) -> Result<&'a CStr, AllocError>

Allocate a CStr from a str.

If src contains a '\0' then the CStr will stop there.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_cstr_from_str("Hello world!")?;
assert_eq!(allocated, c"Hello world!");

let allocated = bump.try_alloc_cstr_from_str("abc\0def")?;
assert_eq!(allocated, c"abc");

pub fn try_alloc_cstr_fmt( &self, args: Arguments<'_>, ) -> Result<&'a CStr, AllocError>

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop there.

If you have a &mut self you can use try_alloc_cstr_fmt_mut instead for better performance.

Errors

Errors if the allocation fails.

Errors if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_cstr_fmt(format_args!("{one} + {two} = {}", one + two))?;
assert_eq!(string, c"1 + 2 = 3");

let one = bump.try_alloc_cstr_fmt(format_args!("{one}\0{two}"))?;
assert_eq!(one, c"1");

pub fn try_alloc_cstr_fmt_mut( &mut self, args: Arguments<'_>, ) -> Result<&'a CStr, AllocError>

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop there.

This function is designed as a performance improvement over try_alloc_cstr_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for its string buffer. As a result, the string buffer rarely needs to grow.

Errors

Errors if the allocation fails.

Errors if a formatting trait implementation returned an error.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_cstr_fmt_mut(format_args!("{one} + {two} = {}", one + two))?;
assert_eq!(string, c"1 + 2 = 3");

let one = bump.try_alloc_cstr_fmt_mut(format_args!("{one}\0{two}"))?;
assert_eq!(one, c"1");

pub fn try_alloc_iter<T>( &self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocate elements of an iterator into a slice.

If you have an impl ExactSizeIterator then you can use try_alloc_iter_exact instead for better performance.

If iter is not an ExactSizeIterator but you have a &mut self you can still get somewhat better performance by using try_alloc_iter_mut.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);

pub fn try_alloc_iter_exact<T, I>( &self, iter: impl IntoIterator<Item = T, IntoIter = I>, ) -> Result<BumpBox<'a, [T]>, AllocError>

where I: ExactSizeIterator<Item = T>,

Allocate elements of an ExactSizeIterator into a slice.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter_exact([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);

pub fn try_alloc_iter_mut<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocate elements of an iterator into a slice.

This function is designed as a performance improvement over try_alloc_iter. By taking self as &mut, it can use the entire remaining chunk space as the capacity for its vector. As a result, the vector rarely needs to grow.

When bumping downwards, prefer try_alloc_iter_mut_rev instead.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter_mut([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);

pub fn try_alloc_iter_mut_rev<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'a, [T]>, AllocError>

Allocate elements of an iterator into a slice in reverse order.

Compared to try_alloc_iter_mut this function is more performant for downwards bumping allocators as the allocation for the vector can be shrunk in place without any ptr::copy.

The reverse is true when upwards allocating. In that case it’s better to use try_alloc_iter_mut to prevent the ptr::copy.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter_mut_rev([1, 2, 3])?;
assert_eq!(slice, [3, 2, 1]);

pub fn try_alloc_uninit<T>( &self, ) -> Result<BumpBox<'a, MaybeUninit<T>>, AllocError>

Allocate an unitialized object.

You can safely initialize the object with init or unsafely with assume_init.

Errors

Errors if the allocation fails.

Examples

Safely:

let five = bump.try_alloc_uninit()?;

let five = five.init(5);

assert_eq!(*five, 5);

Unsafely:

let mut five = bump.try_alloc_uninit()?;

let five = unsafe {
    five.write(5);
    five.assume_init()
};

assert_eq!(*five, 5);

pub fn try_alloc_uninit_slice<T>( &self, len: usize, ) -> Result<BumpBox<'a, [MaybeUninit<T>]>, AllocError>

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone or unsafely with assume_init.

Errors

Errors if the allocation fails.

Examples

Safely:

let values = bump.try_alloc_uninit_slice(3)?;

let values = values.init_copy(&[1, 2, 3]);

assert_eq!(values, [1, 2, 3]);

Unsafely:

let mut values = bump.try_alloc_uninit_slice(3)?;

let values = unsafe {
    values[0].write(1);
    values[1].write(2);
    values[2].write(3);

    values.assume_init()
};

assert_eq!(values, [1, 2, 3]);

pub fn try_alloc_uninit_slice_for<T>( &self, slice: &[T], ) -> Result<BumpBox<'a, [MaybeUninit<T>]>, AllocError>

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone or unsafely with assume_init.

This is just like try_alloc_uninit_slice but uses a slice to provide the len. This avoids a check for a valid layout. The elements of slice are irrelevant.

Errors

Errors if the allocation fails.

Examples

let slice = &[1, 2, 3];
let other_slice = bump.try_alloc_uninit_slice_for(slice)?;
assert_eq!(other_slice.len(), 3);

pub fn try_alloc_fixed_vec<T>( &self, capacity: usize, ) -> Result<FixedBumpVec<'a, T>, AllocError>

Allocate a FixedBumpVec with the given capacity.

Errors

Errors if the allocation fails.

Examples

let mut values = bump.try_alloc_fixed_vec(3)?;
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3]);

pub fn try_alloc_fixed_string( &self, capacity: usize, ) -> Result<FixedBumpString<'a>, AllocError>

Allocate a FixedBumpString with the given capacity in bytes.

Errors

Errors if the allocation fails.

Examples

let mut string = bump.try_alloc_fixed_string(12)?;
string.push_str("Hello");
string.push_str(" world!");
assert_eq!(string, "Hello world!");

pub fn try_alloc_layout( &self, layout: Layout, ) -> Result<NonNull<u8>, AllocError>

Allocates memory as described by the given Layout.

Errors

Errors if the allocation fails.

pub fn try_reserve_bytes(&self, additional: usize) -> Result<(), AllocError>

Reserves capacity for at least additional more bytes to be bump allocated. The bump allocator may reserve more space to avoid frequent reallocations. After calling reserve_bytes, self.stats().remaining() will be greater than or equal to additional. Does nothing if the capacity is already sufficient.

Errors

Errors if the allocation fails.

Examples

let bump: Bump = Bump::try_new()?;
assert!(bump.stats().capacity() < 4096);

bump.try_reserve_bytes(4096)?;
assert!(bump.stats().capacity() >= 4096);

impl<'a, A, const MIN_ALIGN: usize, const UP: bool> BumpScope<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator,

Functions to allocate. Available as fallible or infallible.

pub fn alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'a, T>, E>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

There is also alloc_try_with_mut, optimized for a mutable reference.

Panics

Panics if the allocation fails.

Examples

let result = bump.alloc_try_with(|| -> Result<i32, i32> { Ok(123) });
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.alloc_try_with(|| -> Result<i32, i32> { Err(123) });
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

pub fn alloc_try_with_mut<T, E>( &mut self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'a, T>, E>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

This is just like alloc_try_with, but optimized for a mutable reference.

Panics

Panics if the allocation fails.

Examples

let result = bump.alloc_try_with_mut(|| -> Result<i32, i32> { Ok(123) });
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.alloc_try_with_mut(|| -> Result<i32, i32> { Err(123) });
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

pub fn try_alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<Result<BumpBox<'a, T>, E>, AllocError>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

There is also try_alloc_try_with_mut, optimized for a mutable reference.

Errors

Errors if the allocation fails.

Examples

let result = bump.try_alloc_try_with(|| -> Result<i32, i32> { Ok(123) })?;
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.try_alloc_try_with(|| -> Result<i32, i32> { Err(123) })?;
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

pub fn try_alloc_try_with_mut<T, E>( &mut self, f: impl FnOnce() -> Result<T, E>, ) -> Result<Result<BumpBox<'a, T>, E>, AllocError>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

This is just like try_alloc_try_with, but optimized for a mutable reference.

Errors

Errors if the allocation fails.

Examples

let result = bump.try_alloc_try_with_mut(|| -> Result<i32, i32> { Ok(123) })?;
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.try_alloc_try_with_mut(|| -> Result<i32, i32> { Err(123) })?;
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

Trait Implementations

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Allocator for &mut BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to allocate a block of memory.

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

🔬This is a nightly-only experimental API. (allocator_api)

Deallocates the memory referenced by ptr.

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to extend the memory block.

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like grow, but also ensures that the new contents are set to zero before being returned.

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to shrink the memory block.

fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

fn by_ref(&self) -> &Self

where Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api)

Creates a “by reference” adapter for this instance of Allocator.

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Allocator for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to allocate a block of memory.

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

🔬This is a nightly-only experimental API. (allocator_api)

Deallocates the memory referenced by ptr.

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to extend the memory block.

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like grow, but also ensures that the new contents are set to zero before being returned.

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to shrink the memory block.

fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

fn by_ref(&self) -> &Self

where Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api)

Creates a “by reference” adapter for this instance of Allocator.

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpAllocator for &mut BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

fn stats(&self) -> Stats<'_>

Returns a type which provides statistics about the memory usage of the bump allocator.

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpAllocator for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

fn stats(&self) -> Stats<'_>

Returns a type which provides statistics about the memory usage of the bump allocator.

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Debug for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

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

Formats the value using the given formatter.

impl<'b, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> From<&'b Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>> for &'b BumpScope<'b, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

fn from(value: &'b Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>) -> Self

Converts to this type from the input type.

impl<'b, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> From<&'b mut Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>> for &'b mut BumpScope<'b, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

fn from(value: &'b mut Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>) -> Self

Converts to this type from the input type.

impl<'a, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpAllocatorScope<'a> for &mut BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

impl<'a, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> BumpAllocatorScope<'a> for BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> MutBumpAllocator for &mut BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> MutBumpAllocator for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

impl<A, const MIN_ALIGN: usize, const UP: bool> NoDrop for BumpScope<'_, A, MIN_ALIGN, UP>

impl<const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool, A> RefUnwindSafe for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED> + UnwindSafe,

impl<const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool, A> UnwindSafe for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED> + UnwindSafe,