1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
//! Growable container builders on [`Arena`]: [`String`] and [`Vec`].
//!
//! All public methods are documented on [`Arena`] itself; this file
//! groups the family together to keep the central `mod.rs` smaller.
use allocator_api2::alloc::{AllocError, Allocator};
use super::{Arena, expect_alloc};
use crate::strings::String;
use crate::vec::Vec;
impl<A: Allocator + Clone> Arena<A> {
/// Create a new, empty growable [`String`](crate::strings::String) backed by this
/// arena. No allocation is performed until the first push.
///
/// # Example
///
/// ```
/// let arena = multitude::Arena::new();
/// let mut s = arena.alloc_string();
/// s.push_str("hello");
/// assert_eq!(&*s, "hello");
/// ```
#[must_use]
#[inline]
pub const fn alloc_string(&self) -> String<'_, A> {
String::new_in(self)
}
/// Create a new growable arena-backed [`String`](crate::strings::String) with capacity.
///
/// At least `cap` bytes are pre-allocated.
///
/// # Panics
///
/// Panics if the backing allocator fails. Use
/// [`Self::try_alloc_string_with_capacity`] for a fallible variant.
///
/// # Example
///
/// ```
/// let arena = multitude::Arena::new();
/// let mut s = arena.alloc_string_with_capacity(64);
/// s.push_str("preallocated");
/// assert!(s.capacity() >= 64);
/// ```
#[must_use]
#[inline]
pub fn alloc_string_with_capacity(&self, cap: usize) -> String<'_, A> {
expect_alloc(self.try_alloc_string_with_capacity(cap))
}
/// Fallible variant of [`Self::alloc_string_with_capacity`].
///
/// # Errors
///
/// Returns [`AllocError`] if the backing allocator fails.
#[inline]
pub fn try_alloc_string_with_capacity(&self, cap: usize) -> Result<String<'_, A>, AllocError> {
String::try_with_capacity_in(cap, self)
}
/// Create a new, empty growable [`Vec`](crate::vec::Vec) backed by this arena.
/// No allocation is performed until the first push.
///
/// # Example
///
/// ```
/// let arena = multitude::Arena::new();
/// let mut v = arena.alloc_vec::<u32>();
/// v.push(1);
/// v.push(2);
/// assert_eq!(v.as_slice(), &[1, 2]);
/// ```
#[must_use]
#[inline]
pub const fn alloc_vec<T>(&self) -> Vec<'_, T, A> {
Vec::new_in(self)
}
/// Create a new growable arena-backed [`Vec`](crate::vec::Vec) with capacity.
///
/// At least `cap` elements of capacity are pre-allocated.
///
/// # Panics
///
/// Panics if the backing allocator fails or if the data alignment is at least 32 KiB.
/// Use [`Self::try_alloc_vec_with_capacity`] for a fallible variant.
///
/// # Example
///
/// ```
/// let arena = multitude::Arena::new();
/// let mut v = arena.alloc_vec_with_capacity::<u32>(100);
/// for i in 0..50 {
/// v.push(i);
/// }
/// assert!(v.capacity() >= 100);
/// ```
#[must_use]
#[inline]
pub fn alloc_vec_with_capacity<T>(&self, cap: usize) -> Vec<'_, T, A> {
expect_alloc(self.try_alloc_vec_with_capacity(cap))
}
/// Fallible variant of [`Self::alloc_vec_with_capacity`].
///
/// # Errors
///
/// Returns [`AllocError`] if the backing allocator fails or if the data alignment
/// is at least 32 KiB.
#[inline]
pub fn try_alloc_vec_with_capacity<T>(&self, cap: usize) -> Result<Vec<'_, T, A>, AllocError> {
Vec::try_with_capacity_in(cap, self)
}
}