From 1947104a126107303b4f923dcea639de7cabb93a Mon Sep 17 00:00:00 2001 From: Caio Date: Fri, 20 Nov 2020 15:46:27 -0300 Subject: [PATCH 1/3] A new stack-based vector --- text/2978-stack_based_vec.md | 281 +++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 text/2978-stack_based_vec.md diff --git a/text/2978-stack_based_vec.md b/text/2978-stack_based_vec.md new file mode 100644 index 00000000000..2558bc871bc --- /dev/null +++ b/text/2978-stack_based_vec.md @@ -0,0 +1,281 @@ +- Feature Name: `stack_based_vec` +- Start Date: 2020-09-27 +- RFC PR: [rust-lang/rfcs#2990](https://github.com/rust-lang/rfcs/pull/2990) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +This RFC, which depends and takes advantage of the upcoming stabilization of constant generics (min_const_generics), tries to propose the creation of a new "growable" vector named `ArrayVec` that manages stack memory and can be seen as an alternative for the built-in structure that handles heap-allocated memory, aka `alloc::vec::Vec`. + +# Motivation +[motivation]: #motivation + +`core::collections::ArrayVec` has several use-cases and should be conveniently added into the standard library due to its importance. + +### Unification + +There are a lot of different crates about the subject that tries to do roughly the same thing, a centralized implementation would stop the current fragmentation. + +### Optimization + +Stack-based allocation is generally faster than heap-based allocation and can be used as an optimization in places that otherwise would have to call an allocator. Some resource-constrained embedded devices can also benefit from it. + +### Building block + +Just like `Vec`, `ArrayVec` is also a primitive vector where high-level structures can use it as a building block. For example, a stack-based matrix or binary heap. + +### Useful in the real world + +`arrayvec` is one of the most downloaded project of `crates.io` and is used by thousand of projects, including Rustc itself. + + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +`ArrayVec` is a container that encapsulates fixed size buffers. + +```rust +let mut v: ArrayVec = ArrayVec::new(); +let _ = v.push(1); +let _ = v.push(2); + +assert_eq!(v.len(), 2); +assert_eq!(v[0], 1); + +assert_eq!(v.pop(), Some(2)); +assert_eq!(v.len(), 1); + +v[0] = 7; +assert_eq!(v[0], 7); + +v.extend([1, 2, 3].iter().copied()); + +for element in &v { + println!("{}", element); +} +assert_eq!(v, [7, 1, 2, 3]); +``` + +Instead of relying on a heap-allocator, stack-based memory area is added and removed on-demand in a last-in-first-out (LIFO) order according to the calling workflow of a program. `ArrayVec` takes advantage of this predictable behavior to reserve an exactly amount of uninitialized bytes up-front and these bytes form a buffer where elements can be included dynamically. + +```rust +// `array_vec` can store up to 64 elements +let mut array_vec: ArrayVec = ArrayVec::new(); +``` + +Of course, fixed buffers lead to inflexibility because unlike `Vec`, the underlying capacity can not expand at run-time and there will never be more than 64 elements in the above example. + +```rust +// This vector can store up to 0 elements, therefore, nothing at all +let mut array_vec: ArrayVec = ArrayVec::new(); +let push_result = array_vec.push(1); +// Ooppss... Our push operation wasn't successful +assert!(push_result.is_err()); +``` + +A good question is: Should I use `core::collections::ArrayVec` or `alloc::collections::Vec`? Well, `Vec` is already good enough for most situations while stack allocation usually shines for small sizes. + +* Do you have a known upper bound? + +* How much memory are you going to allocate for your program? The default values of `RUST_MIN_STACK` or `ulimit -s` might not be enough. + +* Are you using nested `Vec`s? `Vec>` might be better than `Vec>`. + +Each use-case is different and should be pondered individually. In case of doubt, stick with `Vec`. + +For a more technical overview, take a look at the following operations: + +```rust +// `array_vec` has a pre-allocated memory of 2048 bits (32 * 64) that can store up +// to 64 decimals. +let mut array_vec: ArrayVec = ArrayVec::new(); + +// Although reserved, there isn't anything explicitly stored yet +assert_eq!(array_vec.len(), 0); + +// Initializes the first 32 bits with a simple '1' decimal or +// 00000000 00000000 00000000 00000001 bits +array_vec.push(1); + +// Our vector memory is now split into a 32/2016 pair of initialized and +// uninitialized memory respectively +assert_eq!(array_vec.len(), 1); +``` + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +`ArrayVec` is a contiguous memory block where elements can be collected, therefore, a collection by definition and even though `core::collections` doesn't exist, it is the most natural module placement. + +The API basically mimics most of the current `Vec` surface with some tweaks to manage capacity. + +Notably, these tweaked methods are checked (out-of-bound inputs or invalid capacity) versions of some well-known functions like `push` that will return `Result` instead of panicking at run-time. Since the upper capacity bound is known at compile-time and the majority of methods are `#[inline]`, the compiler is likely going to remove most of the conditional bounding checking. + +```rust +// Please, bare in mind that these methods are simply suggestions. Discussions about the +// API should probably take place elsewhere. + +pub struct ArrayVec { + data: MaybeUninit<[T; N]>, + len: usize, +} + +impl ArrayVec { + // Constructors + + pub const fn from_array(array: [T; N]) -> Self; + + pub const fn from_array_and_len(array: [T; N], len: usize) -> Self; + + pub const fn new() -> Self; + + // Methods + + pub const fn as_mut_ptr(&mut self) -> *mut T; + + pub const fn as_mut_slice(&mut self) -> &mut [T]; + + pub const fn as_ptr(&self) -> *const T; + + pub const fn as_slice(&self) -> &[T]; + + pub const fn capacity(&self) -> usize; + + pub fn clear(&mut self); + + pub fn dedup(&mut self) + where + T: PartialEq; + + pub fn dedup_by(&mut self, same_bucket: F) + where + F: FnMut(&mut T, &mut T) -> bool; + + pub fn dedup_by_key(&mut self, mut key: F) + where + F: FnMut(&mut T) -> K, + K: PartialEq; + + pub fn drain(&mut self, range: R) -> Option> + where + R: RangeBounds; + + pub fn extend_from_cloneable_slice<'a>(&mut self, other: &'a [T]) -> Result<(), &'a [T]> + where + T: Clone; + + pub fn extend_from_copyable_slice<'a>(&mut self, other: &'a [T]) -> Result<(), &'a [T]> + where + T: Copy; + + pub fn insert(&mut self, idx: usize, element: T) -> Result<(), T>; + + pub const fn is_empty(&self) -> bool; + + pub const fn len(&self) -> usize; + + pub fn pop(&mut self) -> Option; + + pub fn push(&mut self, element: T) -> Result<(), T>; + + pub fn remove(&mut self, idx: usize) -> Option; + + pub fn retain(&mut self, mut f: F) + where + F: FnMut(&mut T) -> bool; + + pub fn splice(&mut self, range: R, replace_with: I) -> Option> + where + I: IntoIterator, + R: RangeBounds; + + pub fn split_off(&mut self, at: usize) -> Option; + + pub fn swap_remove(&mut self, idx: usize) -> Option; + + pub fn truncate(&mut self, len: usize); +} +``` + +Meaningless, unstable and deprecated methods like `reserve` or `drain_filter` weren't considered. A concrete implementation is available at https://github.com/c410-f3r/stack-based-vec. + +# Drawbacks +[drawbacks]: #drawbacks + +### Additional complexity + +New and existing users are likely to find it difficult to differentiate the purpose of each vector type, especially people that don't have a theoretical background in memory management. + +### The current ecosystem is fine + +`ArrayVec` might be an overkill in certain situations. If someone wants to use stack memory in a specific application, then it is just a matter of grabbing the appropriated crate. + +# Prior art +[prior-art]: #prior-art + +These are the most known structures: + + * `arrayvec::ArrayVec`: Uses declarative macros and an `Array` trait for implementations but lacks support for arbitrary sizes. + * `heapless::Vec`: With the usage of `typenum`, can support arbitrary sizes without a nightly compiler. + * `staticvec::StaticVec`: Uses unstable constant generics for arrays of arbitrary sizes. + * `tinyvec::ArrayVec`: Supports fixed and arbitrary (unstable feature) sizes but requires `T: Default` for security reasons. + +As seen, there isn't an implementation that stands out among the others because all of them roughly share the same purpose and functionality. Noteworthy is the usage of constant generics that makes it possible to create an efficient and unified approach for arbitrary array sizes. + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +### Nomenclature + +`ArrayVec` will conflict with `arrayvec::ArrayVec` and `tinyvec::ArrayVec`. + +### Prelude + +Should it be included in the prelude? + +### Macros + +```rust +// Instance with 1i32, 2i32 and 3i32 +let _: ArrayVec = array_vec![1, 2, 3]; + +// Instance with 1i32 and 1i32 +let _: ArrayVec = array_vec![1; 2]; +``` + +# Future possibilities +[future-possibilities]: #future-possibilities + +### Dynamic array + +An hydric approach between heap and stack memory could also be provided natively in the future. + +```rust +pub struct DynVec { + // Hides internal implementation + data: DynVecData, +} + +impl DynVec { + // Much of the `Vec` API goes here +} + +// This is just an example. `Vec` could be `Box` and `enum` an `union`. +enum DynVecData { + Heap(Vec), + Inline(ArrayVec), +} +``` + +The above description is very similar to what `smallvec` already does. + +### Generic collections and generic strings + +Many structures that use `alloc::vec::Vec` as the underlying storage can also use stack or hybrid memory, for example, an hypothetical `GenericString`, where `S` is the storage, could be split into: + +```rust +type DynString = GenericString>; +type HeapString = GenericString>; +type StackString = GenericString>; +``` From 126d24b7725148dc0273e6f2e03dc22a7c3f58c9 Mon Sep 17 00:00:00 2001 From: Caio Date: Sat, 16 Jan 2021 14:47:34 -0300 Subject: [PATCH 2/3] Address some comments There are still thigns to review. Just need some time to address everything --- text/2978-stack_based_vec.md | 52 ++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/text/2978-stack_based_vec.md b/text/2978-stack_based_vec.md index 2558bc871bc..6462086be8d 100644 --- a/text/2978-stack_based_vec.md +++ b/text/2978-stack_based_vec.md @@ -11,24 +11,27 @@ This RFC, which depends and takes advantage of the upcoming stabilization of con # Motivation [motivation]: #motivation -`core::collections::ArrayVec` has several use-cases and should be conveniently added into the standard library due to its importance. - -### Unification - -There are a lot of different crates about the subject that tries to do roughly the same thing, a centralized implementation would stop the current fragmentation. +`core::collections::ArrayVec` should be conveniently added into the standard library due to its importance and potential. ### Optimization Stack-based allocation is generally faster than heap-based allocation and can be used as an optimization in places that otherwise would have to call an allocator. Some resource-constrained embedded devices can also benefit from it. -### Building block +### Unstable features and constant functions -Just like `Vec`, `ArrayVec` is also a primitive vector where high-level structures can use it as a building block. For example, a stack-based matrix or binary heap. +By adding `ArrayVec` into the standard library, it will be possible to use internal unstable features to optimize machine code generation and expose public constant functions without the need of a nightly compiler. ### Useful in the real world -`arrayvec` is one of the most downloaded project of `crates.io` and is used by thousand of projects, including Rustc itself. +`arrayvec` is one of the most downloaded project of `crates.io` and is used by thousand of projects, including Rustc itself. Currently ranks ninth in the "Data structures" category and seventy-fifth in the "All Crate" category. +### Building block + +Just like `Vec`, `ArrayVec` is also a primitive vector where high-level structures can use it as a building block. For example, a stack-based matrix or binary heap. + +### Unification + +There are a lot of different crates about the subject that tries to do roughly the same thing, a centralized implementation would stop the current fragmentation. # Guide-level explanation [guide-level-explanation]: #guide-level-explanation @@ -57,13 +60,26 @@ for element in &v { assert_eq!(v, [7, 1, 2, 3]); ``` -Instead of relying on a heap-allocator, stack-based memory area is added and removed on-demand in a last-in-first-out (LIFO) order according to the calling workflow of a program. `ArrayVec` takes advantage of this predictable behavior to reserve an exactly amount of uninitialized bytes up-front and these bytes form a buffer where elements can be included dynamically. +Instead of relying on a heap-allocator, stack-based memory is added and removed on-demand in a last-in-first-out (LIFO) order according to the calling workflow of a program. `ArrayVec` takes advantage of this predictable behavior to reserve an exactly amount of uninitialized bytes up-front and these bytes form a buffer where elements can be included dynamically. ```rust // `array_vec` can store up to 64 elements let mut array_vec: ArrayVec = ArrayVec::new(); ``` +Another potential use-case is the usage within constant environments: + +```rust +const MY_CONST_ARRAY_VEC: ArrayVec = { + let mut v = ArrayVec::new(); + let _ = v.try_push(1); + let _ = v.try_push(2); + let _ = v.try_push(3); + let _ = v.try_push(4); + v +}; +``` + Of course, fixed buffers lead to inflexibility because unlike `Vec`, the underlying capacity can not expand at run-time and there will never be more than 64 elements in the above example. ```rust @@ -74,13 +90,13 @@ let push_result = array_vec.push(1); assert!(push_result.is_err()); ``` -A good question is: Should I use `core::collections::ArrayVec` or `alloc::collections::Vec`? Well, `Vec` is already good enough for most situations while stack allocation usually shines for small sizes. +A good question is: Should I use `core::collections::ArrayVec` or `alloc::vec::Vec`? Well, `Vec` is already good enough for most situations while stack allocation usually shines for small sizes. * Do you have a known upper bound? * How much memory are you going to allocate for your program? The default values of `RUST_MIN_STACK` or `ulimit -s` might not be enough. -* Are you using nested `Vec`s? `Vec>` might be better than `Vec>`. +* Are you using nested `Vec`s? `Vec>` might be better than `Vec>` because the heap-allocator is only called once instead of the `N` nested calls. Each use-case is different and should be pondered individually. In case of doubt, stick with `Vec`. @@ -88,13 +104,13 @@ For a more technical overview, take a look at the following operations: ```rust // `array_vec` has a pre-allocated memory of 2048 bits (32 * 64) that can store up -// to 64 decimals. +// to 64 signed integers. let mut array_vec: ArrayVec = ArrayVec::new(); // Although reserved, there isn't anything explicitly stored yet assert_eq!(array_vec.len(), 0); -// Initializes the first 32 bits with a simple '1' decimal or +// Initializes the first 32 bits with a simple '1' integer or // 00000000 00000000 00000000 00000001 bits array_vec.push(1); @@ -108,9 +124,9 @@ assert_eq!(array_vec.len(), 1); `ArrayVec` is a contiguous memory block where elements can be collected, therefore, a collection by definition and even though `core::collections` doesn't exist, it is the most natural module placement. -The API basically mimics most of the current `Vec` surface with some tweaks to manage capacity. +The API mimics most of the current `Vec` surface with some additional methods to manage capacity. -Notably, these tweaked methods are checked (out-of-bound inputs or invalid capacity) versions of some well-known functions like `push` that will return `Result` instead of panicking at run-time. Since the upper capacity bound is known at compile-time and the majority of methods are `#[inline]`, the compiler is likely going to remove most of the conditional bounding checking. +Notably, these additional methods are verifiable (out-of-bound inputs or invalid capacity) versions of some well-known functions like `push` that will return `Result` instead of panicking at run-time. Since the upper capacity bound is known at compile-time and the majority of methods are `#[inline]`, the compiler is likely going to remove most of the conditional bounding checking. ```rust // Please, bare in mind that these methods are simply suggestions. Discussions about the @@ -124,10 +140,6 @@ pub struct ArrayVec { impl ArrayVec { // Constructors - pub const fn from_array(array: [T; N]) -> Self; - - pub const fn from_array_and_len(array: [T; N], len: usize) -> Self; - pub const fn new() -> Self; // Methods @@ -249,7 +261,7 @@ let _: ArrayVec = array_vec![1; 2]; ### Dynamic array -An hydric approach between heap and stack memory could also be provided natively in the future. +An hybrid approach between heap and stack memory could also be provided natively in the future. ```rust pub struct DynVec { From 7ebb18920174800b68e5b4a6d9961272e752b82e Mon Sep 17 00:00:00 2001 From: Caio Date: Tue, 19 Jan 2021 20:07:20 -0300 Subject: [PATCH 3/3] Address more comments --- text/2978-stack_based_vec.md | 161 +++++++++++++++++++++++++---------- 1 file changed, 116 insertions(+), 45 deletions(-) diff --git a/text/2978-stack_based_vec.md b/text/2978-stack_based_vec.md index 6462086be8d..fdd7ff56ce7 100644 --- a/text/2978-stack_based_vec.md +++ b/text/2978-stack_based_vec.md @@ -6,7 +6,7 @@ # Summary [summary]: #summary -This RFC, which depends and takes advantage of the upcoming stabilization of constant generics (min_const_generics), tries to propose the creation of a new "growable" vector named `ArrayVec` that manages stack memory and can be seen as an alternative for the built-in structure that handles heap-allocated memory, aka `alloc::vec::Vec`. +This RFC, which depends and takes advantage of the upcoming stabilization of constant generics (min_const_generics), tries to propose the creation of a new vector named `ArrayVec` that manages stack memory and can be seen as an alternative for the built-in structure that handles heap-allocated memory, aka `alloc::vec::Vec`. # Motivation [motivation]: #motivation @@ -40,8 +40,8 @@ There are a lot of different crates about the subject that tries to do roughly t ```rust let mut v: ArrayVec = ArrayVec::new(); -let _ = v.push(1); -let _ = v.push(2); +v.push(1); +v.push(2); assert_eq!(v.len(), 2); assert_eq!(v[0], 1); @@ -60,7 +60,7 @@ for element in &v { assert_eq!(v, [7, 1, 2, 3]); ``` -Instead of relying on a heap-allocator, stack-based memory is added and removed on-demand in a last-in-first-out (LIFO) order according to the calling workflow of a program. `ArrayVec` takes advantage of this predictable behavior to reserve an exactly amount of uninitialized bytes up-front and these bytes form a buffer where elements can be included dynamically. +Instead of relying on a heap-allocator, stack-based memory is added and removed on-demand in a last-in-first-out (LIFO) order according to the calling workflow of a program. `ArrayVec` takes advantage of this predictable behavior to reserve an exactly amount of uninitialized bytes up-front to form an internal buffer. ```rust // `array_vec` can store up to 64 elements @@ -72,10 +72,10 @@ Another potential use-case is the usage within constant environments: ```rust const MY_CONST_ARRAY_VEC: ArrayVec = { let mut v = ArrayVec::new(); - let _ = v.try_push(1); - let _ = v.try_push(2); - let _ = v.try_push(3); - let _ = v.try_push(4); + v.push(1); + v.push(2); + v.push(3); + v.push(4); v }; ``` @@ -85,9 +85,7 @@ Of course, fixed buffers lead to inflexibility because unlike `Vec`, the underly ```rust // This vector can store up to 0 elements, therefore, nothing at all let mut array_vec: ArrayVec = ArrayVec::new(); -let push_result = array_vec.push(1); -// Ooppss... Our push operation wasn't successful -assert!(push_result.is_err()); +array_vec.push(1); // Error! ``` A good question is: Should I use `core::collections::ArrayVec` or `alloc::vec::Vec`? Well, `Vec` is already good enough for most situations while stack allocation usually shines for small sizes. @@ -96,7 +94,50 @@ A good question is: Should I use `core::collections::ArrayVec` or `alloc::vec * How much memory are you going to allocate for your program? The default values of `RUST_MIN_STACK` or `ulimit -s` might not be enough. -* Are you using nested `Vec`s? `Vec>` might be better than `Vec>` because the heap-allocator is only called once instead of the `N` nested calls. +* Are you using nested `Vec`s? `Vec>` might be better than `Vec>`. + +``` +let _: Vec> = vec![vec![1, 2, 3], vec![4, 5]]; + + +-----+-----+-----+ + | ptr | len | cap | + +--|--+-----+-----+ + | + | +---------------------+---------------------+----------+ + | | Vec | Vec | | + | | +-----+-----+-----+ | +-----+-----+-----+ | Unused | + '-> | | ptr | len | cap | | | ptr | len | cap | | capacity | + | +--|--+-----+-----+ | +--|--+-----+-----+ | | + +----|----------------+----|----------------+----------+ + | | + | | +---+---+--------+ + | '-> | 4 | 5 | Unused | + | +---+---+--------+ + | +---+---+---+--------+ + '-> | 1 | 2 | 3 | Unused | + +---+---+---+--------+ + +Illustration credits: @mbartlett21 +``` + +Can you see the `N`, where `N` is length of the external `Vec`, calls to the heap allocator? In the following illustration, the internal `ArrayVec`s are placed contiguously in the same space. + +```txt +let _: Vec> = vec![array_vec![1, 2, 3], array_vec![4, 5]]; + + +-----+-----+-----+ + | ptr | len | cap | + +--|--+-----+-----+ + | + | +------------------------------+--------------------------+----------+ + | | ArrayVec | Arrayvec | | + | | +-----+---+---+---+--------+ | +-----+---+---+--------+ | Unused | + '-> | | len | 1 | 2 | 3 | Unused | | | len | 4 | 5 | Unused | | capacity | + | +-----+---+---+---+--------+ | +-----+---+---+--------+ | | + +------------------------------+--------------------------+----------+ + +Illustration credits: @mbartlett21 +``` Each use-case is different and should be pondered individually. In case of doubt, stick with `Vec`. @@ -124,9 +165,7 @@ assert_eq!(array_vec.len(), 1); `ArrayVec` is a contiguous memory block where elements can be collected, therefore, a collection by definition and even though `core::collections` doesn't exist, it is the most natural module placement. -The API mimics most of the current `Vec` surface with some additional methods to manage capacity. - -Notably, these additional methods are verifiable (out-of-bound inputs or invalid capacity) versions of some well-known functions like `push` that will return `Result` instead of panicking at run-time. Since the upper capacity bound is known at compile-time and the majority of methods are `#[inline]`, the compiler is likely going to remove most of the conditional bounding checking. +To avoid length and conflicting conversations, the API will mimic most of the current `Vec` surface, which also means that all methods that depend on valid user input or valid internal capacity will panic at run-time when something goes wrong. For example, removing an element that is out of bounds. ```rust // Please, bare in mind that these methods are simply suggestions. Discussions about the @@ -142,7 +181,7 @@ impl ArrayVec { pub const fn new() -> Self; - // Methods + // Infallible Methods pub const fn as_mut_ptr(&mut self) -> *mut T; @@ -156,57 +195,48 @@ impl ArrayVec { pub fn clear(&mut self); - pub fn dedup(&mut self) - where - T: PartialEq; + pub const fn is_empty(&self) -> bool; - pub fn dedup_by(&mut self, same_bucket: F) - where - F: FnMut(&mut T, &mut T) -> bool; + pub const fn len(&self) -> usize; - pub fn dedup_by_key(&mut self, mut key: F) + pub fn retain(&mut self, mut f: F) where - F: FnMut(&mut T) -> K, - K: PartialEq; + F: FnMut(&mut T) -> bool; + + pub fn truncate(&mut self, len: usize); + + // Methods that can panic at run-time - pub fn drain(&mut self, range: R) -> Option> + pub fn drain(&mut self, range: R) -> Drain<'_, T, N> where R: RangeBounds; - pub fn extend_from_cloneable_slice<'a>(&mut self, other: &'a [T]) -> Result<(), &'a [T]> + pub fn extend_from_cloneable_slice<'a>(&mut self, other: &'a [T]) where T: Clone; - pub fn extend_from_copyable_slice<'a>(&mut self, other: &'a [T]) -> Result<(), &'a [T]> + pub fn extend_from_copyable_slice<'a>(&mut self, other: &'a [T]) where T: Copy; - pub fn insert(&mut self, idx: usize, element: T) -> Result<(), T>; - - pub const fn is_empty(&self) -> bool; - - pub const fn len(&self) -> usize; - - pub fn pop(&mut self) -> Option; + pub const fn insert(&mut self, idx: usize, element: T); - pub fn push(&mut self, element: T) -> Result<(), T>; + pub const fn push(&mut self, element: T); - pub fn remove(&mut self, idx: usize) -> Option; + pub const fn remove(&mut self, idx: usize) -> T; - pub fn retain(&mut self, mut f: F) - where - F: FnMut(&mut T) -> bool; - - pub fn splice(&mut self, range: R, replace_with: I) -> Option> + pub fn splice(&mut self, range: R, replace_with: I) -> Splice<'_, I::IntoIter, N> where I: IntoIterator, R: RangeBounds; - pub fn split_off(&mut self, at: usize) -> Option; + pub fn split_off(&mut self, at: usize) -> Self; - pub fn swap_remove(&mut self, idx: usize) -> Option; + pub fn swap_remove(&mut self, idx: usize) -> T; - pub fn truncate(&mut self, len: usize); + // Verifiable methods + + pub const fn pop(&mut self) -> Option; } ``` @@ -238,6 +268,47 @@ As seen, there isn't an implementation that stands out among the others because # Unresolved questions [unresolved-questions]: #unresolved-questions +### Verifiable methods + +Unlike methods that will abort the current thread execution, verifiable methods will signal that something has gone wrong or is missing. This approach has two major benefits: + +- `Security`: The user is forced to handle possible variants or corner-cases and enables graceful program shutdown by wrapping everything until `fn main() -> Result<(), MyCustomErrors>` is reached. + +- `Flexibility`: Gives freedom to users because it is possible to choose between, for example, `my_full_array_vec.push(100)?` (check), `my_full_array_vec.push(100).unwrap()` (panic) or `let _ = my_full_array_vec.push(100);` (ignore). + +In regards to performance, since the upper capacity bound is known at compile-time and the majority of methods are `#[inline]`, the compiler will probably have the necessary information to remove most of the conditional bounding checking when producing optimized machine code. + +```rust +pub fn drain(&mut self, range: R) -> Option> +where + R: RangeBounds; + +pub fn extend_from_cloneable_slice<'a>(&mut self, other: &'a [T]) -> Result<(), &'a [T]> +where + T: Clone; + +pub fn extend_from_copyable_slice<'a>(&mut self, other: &'a [T]) -> Result<(), &'a [T]> +where + T: Copy; + +pub const fn insert(&mut self, idx: usize, element: T) -> Result<(), T>; + +pub const fn push(&mut self, element: T) -> Result<(), T>; + +pub const fn remove(&mut self, idx: usize) -> Option; + +pub fn splice(&mut self, range: R, replace_with: I) -> Option> +where + I: IntoIterator, + R: RangeBounds; + +pub fn split_off(&mut self, at: usize) -> Option; + +pub fn swap_remove(&mut self, idx: usize) -> Option; +``` + +In my opinion, every fallible method should either return `Option` or `Result` instead of panicking at run-time. Although the future addition of `try_*` variants can mitigate this situation, it will also bring additional maintenance burden. + ### Nomenclature `ArrayVec` will conflict with `arrayvec::ArrayVec` and `tinyvec::ArrayVec`.