use crate::{alloc::*, EmptyError, NonEmptySlice};
#[cfg(feature = "std")]
use core::num::NonZeroU8;
use core::{
cmp::Ordering,
fmt,
hash::{Hash, Hasher},
mem::MaybeUninit,
num::NonZeroUsize,
ops, ptr,
slice::{self, SliceIndex},
};
/// A vector that is guaranteed to not be empty.
///
/// # [`Deref`](ops::Deref) Behavior
///
/// While [`NonEmptyVec<T>`] should be percieved as a smart pointer to a vector,
/// [`NonEmptyVec<T>`] **does not** dereference to a [`Vec<T>`]. Instead, it
/// dereferences to a [`NonEmptySlice<T>`], which dereferences to
/// [`[T]`](prim@slice). The vector methods present are manual implementations
/// or delegations that preserve the state of the non-empty vector.
///
/// # Layout
///
/// The layout of a [`NonEmptyVec<T>`] is *idential* to [`Vec<T>`].
///
/// # Caveats
///
/// Because [`NonEmptyVec<T>`] **does not** dereference to a vector, using one
/// as a [`&Vec<T>`](Vec) parameter will require the use of [`as_vec`] to
/// "dereference" the [`NonEmptyVec<T>`] as a [`&Vec<T>`](Vec). This is judged
/// as acceptable since [`&Vec<T>`](Vec) parameters are rare in the wild.
///
/// Also, while you **can not** collect a [`NonEmptyVec<T>`] using
/// [`Iterator::collect`], you **can** collect a [`NonEmptyVec<T>`] with the
/// aid of [`IteratorExt`].
///
/// However, unlike most other "not empty" libraries, all other interoperability
/// is remained intact without the need for a new interface. While the previous
/// two cases are incredibly minor, they still are worth listing and considering
/// before you adopt usage.
///
/// [`as_vec`]: NonEmptyVec::as_vec
/// [`IteratorExt`]: crate::iter::IteratorExt
///
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
#[repr(transparent)]
pub struct NonEmptyVec<T> {
pub(crate) inner: Vec<T>,
}
impl<T> NonEmptyVec<T> {
/// This is an incredibly unsafe constructor.
///
/// This creates an *empty* [`NonEmptyVec<T>`]... You understand the risks
/// of that, right? If I could somehow write `unsafe unsafe`, it would be
/// appropriate here.
///
/// You **can not** use any methods inspecting the vector *until* you
/// populate it with at least one element. To fail in doing so results in
/// undefined behavior.
///
/// Unlike [`NonEmptyVec::new_unchecked`], there's no debug assertion. For
/// your sanity, I hope you know what you're doing.
///
/// # Safety
///
/// Using the non-empty vector before populating it is undefined behavior.
///
/// # Examples
///
/// Do not do this:
///
/// ```should_panic
/// use not_empty::NonEmptyVec;
///
/// let empty_nonempty = unsafe { NonEmptyVec::<i32>::empty() };
///
/// // Well, well, well. If it isn't the consequences of my actions.
/// let first = empty_nonempty.first(); // signal 4 (SIGILL); illegal instruction
/// ```
///
/// This, however, is technically fine.
///
/// ```
/// extern crate alloc;
///
/// use alloc::collections::TryReserveError;
/// use not_empty::prelude::*;
///
/// fn process_data(data: &NonEmptySlice<u32>) -> Result<NonEmptyVec<u32>, TryReserveError> {
/// let mut output = unsafe { NonEmptyVec::empty() };
///
/// // Pre-reserve the memory, exiting if we can't
/// output.try_reserve(data.len().get())?;
///
/// // Now we know this can't OOM in the middle of our complex work
/// output.extend(data.iter().map(|&val| {
/// val * 2 + 5 // very complicated
/// }));
///
/// Ok(output)
/// }
/// # process_data(¬_empty_vec![1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
/// ```
#[must_use]
#[inline]
pub unsafe fn empty() -> Self {
NonEmptyVec { inner: Vec::new() }
}
/// An incredibly unsafe constructor. Constructs a new, empty,
/// [`NonEmptyVec<T>`] with at least the specified capacity.
///
/// You **can not** use any methods inspecting the vector *until* you
/// populate it with at least one element. To fail in doing so results in
/// undefined behavior.
///
/// For more information on capacity, refer to [`Vec::with_capacity`].
///
/// # Panics
///
/// Panics if the new capacity exceeds [`isize::MAX`] bytes.
///
/// # Safety
///
/// Using the non-empty vector before populating it is undefined behavior.
///
/// # Examples
///
/// Do not do this:
///
/// ```should_panic
/// use core::num::NonZeroUsize;
/// use not_empty::NonEmptyVec;
///
/// let ten = unsafe { NonZeroUsize::new_unchecked(10) };
/// let empty_nonempty = unsafe { NonEmptyVec::<i32>::with_capacity(ten) };
///
/// // Well, well, well. If it isn't the consequences of my actions.
/// let first = empty_nonempty.first(); // signal 4 (SIGILL); illegal instruction
/// ```
///
/// This, however, is acceptable. However, be sure that it's absolutely
/// required first.
///
/// ```
/// use core::num::NonZeroUsize;
/// use not_empty::NonEmptyVec;
///
/// let ten = unsafe { NonZeroUsize::new_unchecked(10) };
/// let mut nonempty = unsafe { NonEmptyVec::with_capacity(ten) };
/// // Inspecting capacity is literally the only safe operation at this
/// // point in the example.
/// assert!(nonempty.capacity().get() >= 10);
///
/// // These are all done without reallocating...
/// for i in 1..=10 {
/// nonempty.push(i);
/// }
///
/// // Further inspection is now okay since elements have been added:
/// assert_eq!(nonempty.len().get(), 10);
/// assert!(nonempty.capacity().get() >= 10);
///
/// // ... but this may make the vector reallocate
/// nonempty.push(11);
/// assert_eq!(nonempty.len().get(), 11);
/// assert!(nonempty.capacity().get() >= 11);
///
/// // A vector of a zero-sized type will always over-allocate, since no
/// // allocation is necessary.
/// let vec_units: NonEmptyVec<()> = unsafe { NonEmptyVec::with_capacity(ten) };
/// assert_eq!(vec_units.capacity().get(), usize::MAX);
/// ```
#[must_use]
#[inline]
pub unsafe fn with_capacity(capacity: NonZeroUsize) -> Self {
NonEmptyVec {
inner: Vec::with_capacity(capacity.get()),
}
}
/// Creates a new non-empty vector without checking if the given vector is
/// not empty.
///
/// This is a cost-free conversion.
///
/// # Safety
///
/// The vector must not be empty.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use not_empty::NonEmptyVec;
///
/// let vec = vec![1, 2, 3];
/// let nonempty: NonEmptyVec<_> = unsafe { NonEmptyVec::new_unchecked(vec) };
/// ```
///
/// For your convenience, consider using
/// [`not_empty_vec!`](crate::not_empty_vec) instead:
///
/// ```
/// use not_empty::not_empty_vec;
///
/// let nonempty = not_empty_vec![1, 2, 3];
/// ```
#[must_use]
#[inline]
#[track_caller]
pub unsafe fn new_unchecked(vec: Vec<T>) -> Self {
debug_assert!(
!vec.is_empty(),
"non-empty vector initialized with an empty vector"
);
NonEmptyVec { inner: vec }
}
/// Creates a new non-empty vector if the given vector is not empty.
///
/// # Errors
///
/// Returns an [`EmptyError`] if the given vector is empty.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// use not_empty::NonEmptyVec;
///
/// # fn main() -> Result<(), not_empty::EmptyError> {
/// let vec = vec![1, 2, 3];
/// let nonempty: NonEmptyVec<_> = NonEmptyVec::new(vec)?;
/// assert!(nonempty.len().get() == 3);
///
/// let empty: Vec<i32> = vec![];
/// assert!(NonEmptyVec::new(empty).is_err());
/// # Ok(())
/// # }
/// ```
#[inline]
pub fn new(vec: Vec<T>) -> Result<Self, EmptyError> {
(!vec.is_empty())
.then(|| unsafe { NonEmptyVec::new_unchecked(vec) })
.ok_or(EmptyError)
}
/// Creates a `NonEmptyVec<T>` directly from the raw components of another
/// vector.
///
/// # Safety
///
/// This is highly unsafe, due to the number of invariants that aren't
/// checked:
///
/// * `ptr` needs to have been previously allocated via
/// [`String`]/[`Vec<T>`] (at least, it's highly likely to be incorrect
/// if it wasn't.)
/// * `T` needs to have the same alignment as what `ptr` was allocated with.
/// (`T` having a less strict alignment is not sufficient, the alignment
/// really needs to be equal to satisfy the [`dealloc`] requirement that
/// memory must be allocated and deallocated with the same layout.)
/// * The size of `T` times the `capacity` (ie. the allocated size in bytes)
/// needs to be the same size as the pointer was allocated with. (Because
/// similar to alignment, [`dealloc`] must be called with the same layout
/// `size`.)
/// * `length` needs to be less than or equal to `capacity`.
///
/// Violating these may cause problems like corrupting the allocator's
/// internal data structures. For example it is normally **not** safe
/// to build a [`NonEmptyVec<u8>`] from a pointer to a C `char` array with
/// length `size_t`, doing so is only safe if the array was initially
/// allocated by a `Vec` or `String`. It's also not safe to build one from a
/// `NonEmptyVec<u16>` and its length, because the allocator cares about the
/// alignment, and these two types have different alignments. The buffer was
/// allocated with alignment 2 (for `u16`), but after turning it into a
/// `NonEmptyVec<u8>` it'll be deallocated with alignment 1. To avoid these
/// issues, it is often preferable to do casting/transmuting using
/// [`slice::from_raw_parts`](crate::slice::from_raw_parts) instead.
///
/// The ownership of `ptr` is effectively transferred to the
/// [`NonEmptyVec<T>`] which may then deallocate, reallocate or change the
/// contents of memory pointed to by the pointer at will. Ensure
/// that nothing else uses the pointer after calling this
/// function.
///
/// [`dealloc`]: std::alloc::GlobalAlloc::dealloc
#[must_use]
#[inline]
pub unsafe fn from_raw_parts(
ptr: *mut T,
length: NonZeroUsize,
capacity: NonZeroUsize,
) -> Self {
let vec = Vec::from_raw_parts(ptr, length.get(), capacity.get());
NonEmptyVec::new_unchecked(vec)
}
/// Returns a reference to the underlying vector.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// fn needs_vec_ref(vec: &Vec<i32>) {
/// // ...
/// }
///
/// let nonempty = not_empty::vec![1, 2, 3];
/// needs_vec_ref(nonempty.as_vec());
/// ```
#[must_use]
#[inline]
pub fn as_vec(&self) -> &Vec<T> {
&self.inner
}
/// Converts the [`NonEmptyVec<T>`] back into a [`Vec<T>`].
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// fn needs_vec(vec: Vec<i32>) {
/// // ...
/// }
///
/// let nonempty = not_empty::vec![1, 2, 3];
/// needs_vec(nonempty.into_vec());
/// ```
#[must_use]
#[inline]
pub fn into_vec(self) -> Vec<T> {
self.inner
}
/// Returns the number of elements the vector can hold without reallocating.
///
/// Unlike [`Vec::capacity`], this returns a [`NonZeroUsize`] instead of
/// a [`usize`].
///
/// # Examples
///
/// ```
/// let nonempty = not_empty::vec![1, 2, 3];
/// assert!(nonempty.capacity().get() == 3);
/// ```
#[must_use]
#[inline]
pub fn capacity(&self) -> NonZeroUsize {
unsafe { NonZeroUsize::new_unchecked(self.inner.capacity()) }
}
/// Reserves capacity for at least `additional` more elements to be inserted
/// in the given `NonEmptyVec<T>`. The collection may reserve more space to
/// speculatively avoid frequent reallocations. After calling `reserve`,
/// capacity will be greater than or equal to `self.len() + additional`.
/// Does nothing if capacity is already sufficient.
///
/// For more information, refer to [`Vec::reserve`].
///
/// # Panics
///
/// Panics if the new capacity exceeds `isize::MAX` bytes.
///
/// # Examples
///
/// ```
/// let mut nonempty = not_empty::vec![1];
/// nonempty.reserve(10);
/// assert!(nonempty.capacity().get() >= 11);
/// ```
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn reserve(&mut self, additional: usize) {
self.inner.reserve(additional);
}
/// Reserves the minimum capacity for at least `additional` more elements to
/// be inserted in the given `NonEmptyVec<T>`. Unlike [`reserve`], this will
/// not deliberately over-allocate to speculatively avoid frequent
/// allocations. After calling `reserve_exact`, capacity will be greater
/// than or equal to `self.len() + additional`. Does nothing if the capacity
/// is already sufficient.
///
/// Note that the allocator may give the collection more space than it
/// requests. Therefore, capacity can not be relied upon to be precisely
/// minimal. Prefer [`reserve`] if future insertions are expected.
///
/// For more information, refer to [`Vec::reserve_exact`]
///
/// [`reserve`]: NonEmptyVec::reserve
///
/// # Panics
///
/// Panics if the new capacity exceeds `isize::MAX` bytes.
///
/// # Examples
///
/// ```
/// let mut nonempty = not_empty::vec![1];
/// nonempty.reserve_exact(10);
/// assert!(nonempty.capacity().get() >= 11);
/// ```
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn reserve_exact(&mut self, additional: usize) {
self.inner.reserve_exact(additional);
}
/// Tries to reserve capacity for at least `additional` more elements to be
/// inserted in the given `NonEmptyVec<T>`. The collection may reserve more
/// space to speculatively avoid frequent reallocations. After calling
/// `try_reserve`, capacity will be greater than or equal to
/// `self.len() + additional` if it returns `Ok(())`. Does nothing if
/// capacity is already sufficient.
///
/// For more information, refer to [`Vec::try_reserve`].
///
/// # Errors
///
/// If the capacity overflows, or the allocator reports a failure, then an error
/// is returned.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// use alloc::collections::TryReserveError;
/// use not_empty::prelude::*;
///
/// fn process_data(data: &NonEmptySlice<u32>) -> Result<NonEmptyVec<u32>, TryReserveError> {
/// let mut output = unsafe { NonEmptyVec::empty() };
///
/// // Pre-reserve the memory, exiting if we can't
/// output.try_reserve(data.len().get())?;
///
/// // Now we know this can't OOM in the middle of our complex work
/// output.extend(data.iter().map(|&val| {
/// val * 2 + 5 // very complicated
/// }));
///
/// Ok(output)
/// }
/// # process_data(¬_empty_vec![1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
/// ```
#[inline]
pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
self.inner.try_reserve(additional)
}
/// Tries to reserve the minimum capacity for at least `additional`
/// elements to be inserted in the given `Vec<T>`. Unlike [`try_reserve`],
/// this will not deliberately over-allocate to speculatively avoid frequent
/// allocations. After calling `try_reserve_exact`, capacity will be greater
/// than or equal to `self.len() + additional` if it returns `Ok(())`.
/// Does nothing if the capacity is already sufficient.
///
/// Note that the allocator may give the collection more space than it
/// requests. Therefore, capacity can not be relied upon to be precisely
/// minimal. Prefer [`try_reserve`] if future insertions are expected.
///
/// [`try_reserve`]: NonEmptyVec::try_reserve
///
/// # Errors
///
/// If the capacity overflows, or the allocator reports a failure, then an error
/// is returned.
///
/// # Examples
///
/// ```
/// # extern crate alloc;
/// use alloc::collections::TryReserveError;
/// use not_empty::prelude::*;
///
/// fn process_data(data: &NonEmptySlice<u32>) -> Result<NonEmptyVec<u32>, TryReserveError> {
/// let mut output = unsafe { NonEmptyVec::empty() };
///
/// // Pre-reserve the memory, exiting if we can't
/// output.try_reserve_exact(data.len().get())?;
///
/// // Now we know this can't OOM in the middle of our complex work
/// output.extend(data.iter().map(|&val| {
/// val * 2 + 5 // very complicated
/// }));
///
/// Ok(output)
/// }
/// # process_data(¬_empty_vec![1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
/// ```
#[inline]
pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> {
self.inner.try_reserve_exact(additional)
}
/// Shrinks the capacity of the vector as much as possible.
///
/// It will drop down as close as possible to the length but the allocator
/// may still inform the vector that there is space for a few more elements.
///
/// For more information, refer to [`Vec::shrink_to_fit`].
///
/// # Examples
///
/// ```
/// use core::num::NonZeroUsize;
/// use not_empty::NonEmptyVec;
///
/// let mut nonempty = unsafe { NonEmptyVec::with_capacity(NonZeroUsize::new_unchecked(10)) };
/// nonempty.extend([1, 2, 3]);
/// assert_eq!(nonempty.capacity().get(), 10);
/// nonempty.shrink_to_fit();
/// assert!(nonempty.capacity().get() >= 3);
/// ```
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn shrink_to_fit(&mut self) {
self.inner.shrink_to_fit();
}
/// Shrinks the capacity of the vector with a lower bound.
///
/// The capacity will remain at least as large as both the length and the
/// supplied value.
///
/// If the current capacity is less than the lower limit, this is a no-op.
///
/// For more information, refer to [`Vec::shrink_to`].
///
/// # Examples
///
/// ```
/// use core::num::NonZeroUsize;
/// use not_empty::NonEmptyVec;
///
/// let mut nonempty = unsafe { NonEmptyVec::with_capacity(NonZeroUsize::new_unchecked(10)) };
/// nonempty.extend([1, 2, 3]);
/// assert_eq!(nonempty.capacity().get(), 10);
///
/// nonempty.shrink_to(4);
/// assert!(nonempty.capacity().get() >= 4);
///
/// nonempty.shrink_to(0);
/// assert!(nonempty.capacity().get() >= 3);
/// ```
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn shrink_to(&mut self, min_capacity: usize) {
self.inner.shrink_to(min_capacity);
}
/// Converts this [`NonEmptyVec<T>`] into [`Box<NonEmptySlice<T>>`].
///
/// This will drop any excess capacity.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// let nonempty = not_empty::vec![1, 2, 3];
/// let slice = nonempty.into_boxed_slice();
/// ```
///
/// Any excess capacity is removed:
///
/// ```
/// use core::num::NonZeroUsize;
/// use not_empty::{NonEmptySlice, NonEmptyVec};
///
/// let mut nonempty = unsafe { NonEmptyVec::with_capacity(NonZeroUsize::new_unchecked(10)) };
/// nonempty.extend([1, 2 ,3]);
/// assert_eq!(nonempty.capacity().get(), 10);
///
/// let slice: Box<NonEmptySlice<_>> = nonempty.into_boxed_slice();
/// assert_eq!(slice.into_vec().capacity().get(), 3);
/// ```
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[must_use]
#[inline]
pub fn into_boxed_slice(self) -> Box<NonEmptySlice<T>> {
let b = self.inner.into_boxed_slice();
let raw = Box::into_raw(b) as *mut NonEmptySlice<T>;
unsafe { Box::from_raw(raw) }
}
/// Shortens the vector, keeping the first `len` elements and dropping the
/// rest.
///
/// If `len` is greater than the vector's current length, this has no
/// effect.
///
/// The [`drain`](NonEmptyVec::drain) method can emulate `truncate`, but
/// causes the excess elements to be returned instead of dropped.
///
/// This method has no effect on the allocated capacity of the vector.
///
/// # Examples
///
/// Truncating a five element vector to two elements:
///
/// ```
/// use core::num::NonZeroUsize;
///
/// let mut vec = not_empty::vec![1, 2, 3, 4, 5];
/// vec.truncate(unsafe { NonZeroUsize::new_unchecked(2) });
/// assert_eq!(vec, [1, 2]);
/// ```
///
/// No truncation occurs when `len` is greater than the vector's current
/// length:
///
/// ```
/// use core::num::NonZeroUsize;
///
/// let mut vec = not_empty::vec![1, 2, 3];
/// vec.truncate(unsafe { NonZeroUsize::new_unchecked(8) });
/// assert_eq!(vec, [1, 2, 3]);
/// ```
#[inline]
pub fn truncate(&mut self, len: NonZeroUsize) {
self.inner.truncate(len.get());
}
/// Extracts a [`NonEmptySlice`] containing the entire vector.
#[must_use]
#[inline]
pub fn as_slice(&self) -> &NonEmptySlice<T> {
unsafe { NonEmptySlice::new_unchecked(&self.inner) }
}
/// Extracts a mutable [`NonEmptySlice`] containing the entire vector.
#[must_use]
#[inline]
pub fn as_mut_slice(&mut self) -> &mut NonEmptySlice<T> {
unsafe { NonEmptySlice::new_mut_unchecked(&mut self.inner) }
}
/// Returns a raw pointer to the vector’s buffer, or a dangling raw pointer
/// valid for zero sized reads if the vector didn’t allocate.
///
/// For more information, refer to [`Vec::as_ptr`].
#[must_use]
#[inline]
pub fn as_ptr(&self) -> *const T {
self.inner.as_ptr()
}
/// Returns an unsafe mutable pointer to the vector’s buffer, or a dangling
/// raw pointer valid for zero sized reads if the vector didn’t allocate.
///
/// For more information, refer to [`Vec::as_mut_ptr`].
#[must_use]
#[inline]
pub fn as_mut_ptr(&mut self) -> *mut T {
self.inner.as_mut_ptr()
}
/// Forces the length of the vector to `new_len`.
///
/// For more information, refer to [`Vec::set_len`].
///
/// # Safety
///
/// * `new_len` must be less than or equal to
/// [`capacity()`](NonEmptyVec::capacity).
/// * The elements at `old_len..new_len` must be initialized.
#[inline]
pub unsafe fn set_len(&mut self, new_len: NonZeroUsize) {
debug_assert!(new_len < self.capacity());
self.inner.set_len(new_len.get());
}
#[inline]
#[track_caller]
fn assert_nonempty(&self, method_name: &'static str) {
#[cfg_attr(panic = "abort", inline)]
#[cfg_attr(not(panic = "abort"), inline(never))]
#[cold]
#[track_caller]
fn assert_failed(method_name: &'static str) {
panic!("{method_name} left the NonEmptyVec empty");
}
if cfg!(debug_assertions) && self.inner.is_empty() {
assert_failed(method_name);
}
}
/// Removes an element from the vector and returns it.
///
/// The removed element is replaced by the last element of the vector..
///
/// This does not preserve ordering, but is *O*(1). If you need to preserve
/// the element order, use [`remove`](NonEmptyVec::remove) instead.
///
/// # Panics
///
/// Panics if `index` is out of bounds.
///
/// # Safety
///
/// This can not leave the [`NonEmptyVec`] empty. If it does, on debug
/// builds, it will panic. Otherwise, it is undefined behavior. Consider
/// whether or not a [`NonEmptyVec`] is really the right choice for your
/// application.
#[must_use]
#[inline]
#[track_caller]
pub unsafe fn swap_remove(&mut self, index: usize) -> T {
let element = self.inner.swap_remove(index);
self.assert_nonempty("swap_remove");
element
}
/// Inserts an element at position `index` within the vector, shifting all
/// elements after it to the right.
///
/// For more information, refer to [`Vec::insert`].
///
/// # Panics
///
/// Panics if `index > len`.
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
#[track_caller]
pub fn insert(&mut self, index: usize, element: T) {
self.inner.insert(index, element);
}
/// Removes and returns the element at position `index` within the vector,
/// shifting all elements after it to the left.
///
/// Because this shifts over the remaining elements, it has a worst-case
/// performance of *O*(*n*). If you don't need the order of elements
/// to be preserved, use [`swap_remove`](NonEmptyVec::swap_remove) instead.
///
/// For more information, refer to [`Vec::swap_remove`].
///
/// # Panics
///
/// Panics if `index` is out of bounds.
///
/// # Safety
///
/// This can not leave the [`NonEmptyVec`] empty. If it does, on debug
/// builds, it will panic. Otherwise, it is undefined behavior. Consider
/// whether or not a [`NonEmptyVec`] is really the right choice for your
/// application.
#[must_use]
#[inline]
#[track_caller]
pub unsafe fn remove(&mut self, index: usize) -> T {
let element = self.inner.remove(index);
self.assert_nonempty("remove");
element
}
/// Retains only the elements specified by the predicate.
///
/// In other words, remove all elements `e` for which `f(&e)` returns `false`.
/// This method operates in place, visiting each element exactly once in the
/// original order, and preserves the order of the retained elements.
///
/// For more information, refer to [`Vec::retain`].
///
/// # Safety
///
/// This can not leave the [`NonEmptyVec`] empty. If it does, on debug
/// builds, it will panic. Otherwise, it is undefined behavior. Consider
/// whether or not a [`NonEmptyVec`] is really the right choice for your
/// application.
#[inline]
#[track_caller]
pub unsafe fn retain<F>(&mut self, f: F)
where
F: FnMut(&T) -> bool,
{
self.inner.retain(f);
self.assert_nonempty("retain");
}
/// Retains only the elements specified by the predicate, passing a mutable
/// reference to it.
///
/// In other words, remove all elements `e` such that `f(&mut e)` returns
/// `false`. This method operates in place, visiting each element exactly
/// once in the original order, and preserves the order of the retained
/// elements.
///
/// For more information, refer to [`Vec::retain_mut`].
///
/// # Safety
///
/// This can not leave the [`NonEmptyVec`] empty. If it does, on debug
/// builds, it will panic. Otherwise, it is undefined behavior. Consider
/// whether or not a [`NonEmptyVec`] is really the right choice for your
/// application.
#[inline]
#[track_caller]
pub unsafe fn retain_mut<F>(&mut self, f: F)
where
F: FnMut(&mut T) -> bool,
{
self.inner.retain_mut(f);
self.assert_nonempty("retain_mut");
}
/// Removes all but the first of consecutive elements in the vector that
/// resolve to the same key.
///
/// If the vector is sorted, this removes all duplicates.
///
/// For more information, refer to [`Vec::dedup_by_key`].
#[inline]
pub fn dedup_by_key<F, K>(&mut self, key: F)
where
F: FnMut(&mut T) -> K,
K: PartialEq,
{
self.inner.dedup_by_key(key);
}
/// Removes all but the first of consecutive elements in the vector
/// satisfying a given equality relation.
///
/// The `same_bucket` function is passed references to two elements from the
/// vector and must determine if the elements compare equal. The elements
/// are passed in opposite order from their order in the slice, so if
/// `same_bucket(a, b)` returns `true`, `a` is removed.
///
/// If the vector is sorted, this removes all duplicates.
///
/// For more information, refer to [`Vec::dedup_by`].
#[inline]
pub fn dedup_by<F>(&mut self, same_bucket: F)
where
F: FnMut(&mut T, &mut T) -> bool,
{
self.inner.dedup_by(same_bucket);
}
/// Appends an element to the back of a collection.
///
/// For more information, refer to [`Vec::push`].
///
/// # Panics
///
/// Panics if the new capacity exceeds [`isize::MAX`] bytes.
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
#[track_caller]
pub fn push(&mut self, value: T) {
self.inner.push(value);
}
/// Removes the last element from a vector and returns it.
///
/// Unlike [`Vec::pop`], this is never an [`Option`].
///
/// # Safety
///
/// This can not leave the [`NonEmptyVec`] empty. If it does, on debug
/// builds, it will panic. Otherwise, it is undefined behavior. Consider
/// whether or not a [`NonEmptyVec`] is really the right choice for your
/// application.
#[inline]
#[track_caller]
pub unsafe fn pop(&mut self) -> T {
let element = self.inner.pop().unwrap_unchecked();
self.assert_nonempty("pop");
element
}
/// Moves all the elements of `other` into `self`, leaving `other` empty.
///
/// For more information, refer to [`Vec::append`].
///
/// # Panics
///
/// Panics if the new capacity exceeds `isize::MAX` bytes.
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
#[track_caller]
pub fn append(&mut self, other: &mut Vec<T>) {
self.inner.append(other);
}
/// Removes the specified range from the vector in bulk, returning all
/// removed elements as an iterator. If the iterator is dropped before
/// being fully consumed, it drops the remaining removed elements.
///
/// The returned iterator keeps a mutable borrow on the vector to optimize
/// its implementation.
///
/// # Panics
///
/// Panics if the starting point is greater than the end point or if
/// the end point is greater than the length of the vector.
///
/// # Safety
///
/// This can not leave the [`NonEmptyVec`] empty. If it does, on debug
/// builds, it will panic. Otherwise, it is undefined behavior. Consider
/// whether or not a [`NonEmptyVec`] is really the right choice for your
/// application.
///
/// # Leaking
///
/// If the returned iterator goes out of scope without being dropped (due to
/// [`mem::forget`], for example), the vector may have lost and leaked
/// elements arbitrarily, including elements outside the range.
///
///
/// [`mem::forget`]: core::mem::forget
#[inline]
#[track_caller]
pub unsafe fn drain<R>(&mut self, range: R) -> vec::Drain<'_, T>
where
R: ops::RangeBounds<usize>,
{
// TODO: Use slice::range once stable
#[must_use]
#[track_caller]
fn slice_range_hack<R>(range: R, bounds: ops::RangeTo<usize>) -> ops::Range<usize>
where
R: ops::RangeBounds<usize>,
{
#[cfg_attr(panic = "abort", inline)]
#[cfg_attr(not(panic = "abort"), inline(never))]
#[cold]
#[track_caller]
const fn slice_start_index_overflow_fail() -> ! {
panic!("attempted to index slice from after maximum usize");
}
#[cfg_attr(panic = "abort", inline)]
#[cfg_attr(not(panic = "abort"), inline(never))]
#[cold]
#[track_caller]
const fn slice_end_index_overflow_fail() -> ! {
panic!("attempted to index slice up to maximum usize");
}
#[cfg_attr(panic = "abort", inline)]
#[cfg_attr(not(panic = "abort"), inline(never))]
#[cold]
#[track_caller]
const fn slice_index_order_fail() -> ! {
panic!("slice index start is larger than end");
}
#[cfg_attr(panic = "abort", inline)]
#[cfg_attr(not(panic = "abort"), inline(never))]
#[cold]
#[track_caller]
const fn slice_end_index_len_fail() -> ! {
panic!("slice end index is out of range for slice");
}
let len = bounds.end;
let start = match range.start_bound() {
ops::Bound::Included(&n) => n,
ops::Bound::Excluded(&n) => n
.checked_add(1)
.unwrap_or_else(|| slice_start_index_overflow_fail()),
ops::Bound::Unbounded => 0,
};
let end = match range.end_bound() {
ops::Bound::Included(&n) => n
.checked_add(1)
.unwrap_or_else(|| slice_end_index_overflow_fail()),
ops::Bound::Excluded(&n) => n,
ops::Bound::Unbounded => len,
};
if start > end {
slice_index_order_fail();
}
if end > len {
slice_end_index_len_fail();
}
ops::Range { start, end }
}
#[cfg_attr(panic = "abort", inline)]
#[cfg_attr(not(panic = "abort"), inline(never))]
#[cold]
#[track_caller]
const fn assert_failed() -> ! {
panic!("attempted to drain the entire vector");
}
let len = self.inner.len();
let normalized_range = slice_range_hack(range, ..len);
if cfg!(debug_assertions)
&& normalized_range.start == 0
&& normalized_range.end == (len - 1)
{
assert_failed();
}
self.inner.drain(normalized_range)
}
/// Returns the number of elements in the vector, also referred to as its
/// 'length'.
///
/// Unlike [`Vec::len`], this returrns a [`NonZeroUsize`].
///
/// For more information, refer to [`Vec::len`].
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// let a = not_empty::vec![1, 2, 3];
/// assert_eq!(a.len().get(), 3);
/// ```
#[must_use]
#[inline]
pub fn len(&self) -> NonZeroUsize {
unsafe { NonZeroUsize::new_unchecked(self.inner.len()) }
}
/// Splits the collection into two at the given index.
///
/// Returns a newly allocated vector containing the elements in the range
/// `[at, len)`. After the call, the original vector will be left containing
/// the elements `[0, at)` with its previous capacity unchanged.
///
/// Unlike [`Vec::split_off`], it's impossible to split at index zero.
///
/// # Panics
///
/// Panics if `at > len`.
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[must_use = "use `.truncate()` if you don't need the other half"]
#[inline]
#[track_caller]
pub fn split_off(&mut self, at: NonZeroUsize) -> Vec<T> {
self.inner.split_off(at.get())
}
/// Resizes the `NonEmptyVec` in-place so that `len` is equal to `new_len`.
///
/// If `new_len` is greater than `len`, the `NonEmptyVec` is extended by the
/// difference, with each additional slot filled with the result of
/// calling the closure `f`. The return values from `f` will end up
/// in the `NonEmptyVec` in the order they have been generated.
///
/// If `new_len` is less than `len`, the `NonEmptyVec` is simply truncated.
///
/// This method uses a closure to create new values on every push. If
/// you'd rather [`Clone`] a given value, use [`NonEmptyVec::resize`]. If
/// you want to use the [`Default`] trait to generate values, you can
/// pass [`Default::default`] as the second argument.
///
/// For more information, refer to [`Vec::resize_with`].
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn resize_with<F>(&mut self, new_len: NonZeroUsize, f: F)
where
F: FnMut() -> T,
{
self.inner.resize_with(new_len.get(), f);
}
/// Consumes and leaks the `NonEmptyVec`, returning a mutable reference to
/// the contents, `&'a mut NonEmptySlice<T>`. Note that the type `T` must
/// outlive the chosen lifetime `'a`. If the type has only static
/// references, or none at all, then this may be chosen to be `'static`.
///
/// As of Rust 1.57, this method does not reallocate or shrink the
/// `NonEmptyVec`, so the leaked allocation may include unused capacity that
/// is not part of the returned slice.
///
/// This function is mainly useful for data that lives for the remainder of
/// the program's life. Dropping the returned reference will cause a memory
/// leak.
///
/// For more information, refer to [`Vec::leak`].
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[must_use]
#[inline]
pub fn leak<'a>(self) -> &'a mut NonEmptySlice<T> {
unsafe { NonEmptySlice::new_mut_unchecked(self.inner.leak()) }
}
/// Returns the remaining spare capacity of the vector as a slice of
/// `MaybeUninit<T>`.
///
/// For more information, refer to [`Vec::spare_capacity_mut`].
#[must_use]
#[inline]
pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] {
self.inner.spare_capacity_mut()
}
}
impl<T: Clone> NonEmptyVec<T> {
/// Resizes the `NonEmptyVec` in-place so that `len` is equal to `new_len`.
///
/// If `new_len` is greater than `len`, the `NonEmptyVec` is extended by the
/// difference, with each additional slot filled with `value`.
/// If `new_len` is less than `len`, the `NonEmptyVec` is simply truncated.
///
/// This method requires `T` to implement [`Clone`],
/// in order to be able to clone the passed value.
/// If you need more flexibility (or want to rely on [`Default`] instead of
/// [`Clone`]), use [`NonEmptyVec::resize_with`].
/// If you only need to resize to a smaller size, use
/// [`NonEmptyVec::truncate`].
///
/// For more information, refer to [`Vec::resize`].
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn resize(&mut self, new_len: NonZeroUsize, value: T) {
self.inner.resize(new_len.get(), value);
}
/// Clones and appends all elements in a slice to the `NonEmptyVec`.
///
/// Iterates over the slice `other`, clones each element, and then appends
/// it to this `NonEmptyVec`. The `other` slice is traversed in-order.
///
/// Note that this function is same as [`extend`] except that it is
/// specialized to work with slices instead. If and when Rust gets
/// specialization this function will likely be deprecated (but still
/// available).
///
/// For more information, refer to [`Vec::extend_from_slice`].
///
/// [`extend`]: NonEmptyVec::extend
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
pub fn extend_from_slice(&mut self, other: &[T]) {
self.inner.extend_from_slice(other);
}
/// Copies elements from `src` range to the end of the vector.
///
/// For more information, refer to [`Vec::extend_from_within`].
///
/// # Panics
///
/// Panics if the starting point is greater than the end point or if
/// the end point is greater than the length of the vector.
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
#[inline]
#[track_caller]
pub fn extend_from_within<R>(&mut self, src: R)
where
R: ops::RangeBounds<usize>,
{
self.inner.extend_from_within(src);
}
}
impl<T: PartialEq> NonEmptyVec<T> {
/// Removes consecutive repeated elements in the vector according to the
/// [`PartialEq`] trait implementation.
///
/// If the vector is sorted, this removes all duplicates.
///
/// For more information, refer to [`Vec::dedup`].
#[inline]
pub fn dedup(&mut self) {
self.inner.dedup();
}
}
////////////////////////////////////////////////////////////////////////////////
// Formatting
////////////////////////////////////////////////////////////////////////////////
impl<T> fmt::Debug for NonEmptyVec<T>
where
T: fmt::Debug,
{
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Debug::fmt(&self.inner, f)
}
}
////////////////////////////////////////////////////////////////////////////////
// Cloning
////////////////////////////////////////////////////////////////////////////////
impl<T> Clone for NonEmptyVec<T>
where
T: Clone,
{
#[inline]
fn clone(&self) -> Self {
let vec = self.inner.clone();
unsafe { NonEmptyVec::new_unchecked(vec) }
}
#[inline]
fn clone_from(&mut self, source: &Self) {
self.inner.clone_from(&source.inner);
}
}
////////////////////////////////////////////////////////////////////////////////
// Dereferencing
////////////////////////////////////////////////////////////////////////////////
impl<T> ops::Deref for NonEmptyVec<T> {
type Target = NonEmptySlice<T>;
#[inline]
fn deref(&self) -> &Self::Target {
self.as_slice()
}
}
impl<T> ops::DerefMut for NonEmptyVec<T> {
#[inline]
fn deref_mut(&mut self) -> &mut Self::Target {
self.as_mut_slice()
}
}
////////////////////////////////////////////////////////////////////////////////
// `as_*` traits
////////////////////////////////////////////////////////////////////////////////
impl<T> AsRef<[T]> for NonEmptyVec<T> {
#[inline]
fn as_ref(&self) -> &[T] {
self.as_slice().as_ref()
}
}
impl<T> AsMut<[T]> for NonEmptyVec<T> {
#[inline]
fn as_mut(&mut self) -> &mut [T] {
self.as_mut_slice().as_mut()
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> AsRef<NonEmptySlice<T>> for NonEmptyVec<T> {
#[inline]
fn as_ref(&self) -> &NonEmptySlice<T> {
self.as_slice()
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> AsMut<NonEmptySlice<T>> for NonEmptyVec<T> {
#[inline]
fn as_mut(&mut self) -> &mut NonEmptySlice<T> {
self.as_mut_slice()
}
}
impl<T> AsRef<Vec<T>> for NonEmptyVec<T> {
#[inline]
fn as_ref(&self) -> &Vec<T> {
&self.inner
}
}
////////////////////////////////////////////////////////////////////////////////
// `borrow` implementations
////////////////////////////////////////////////////////////////////////////////
impl<T> Borrow<[T]> for NonEmptyVec<T> {
#[inline]
fn borrow(&self) -> &[T] {
self
}
}
impl<T> BorrowMut<[T]> for NonEmptyVec<T> {
#[inline]
fn borrow_mut(&mut self) -> &mut [T] {
self
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> Borrow<NonEmptySlice<T>> for NonEmptyVec<T> {
#[inline]
fn borrow(&self) -> &NonEmptySlice<T> {
self
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> BorrowMut<NonEmptySlice<T>> for NonEmptyVec<T> {
#[inline]
fn borrow_mut(&mut self) -> &mut NonEmptySlice<T> {
self
}
}
////////////////////////////////////////////////////////////////////////////////
// Index operations
////////////////////////////////////////////////////////////////////////////////
impl<T, I> ops::Index<I> for NonEmptyVec<T>
where
I: SliceIndex<[T]>,
{
type Output = I::Output;
#[inline]
fn index(&self, index: I) -> &Self::Output {
ops::Index::index(&self.inner, index)
}
}
impl<T, I> ops::IndexMut<I> for NonEmptyVec<T>
where
I: SliceIndex<[T]>,
{
#[inline]
fn index_mut(&mut self, index: I) -> &mut Self::Output {
ops::IndexMut::index_mut(&mut self.inner, index)
}
}
////////////////////////////////////////////////////////////////////////////////
// Iterator traits
////////////////////////////////////////////////////////////////////////////////
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
impl<'a, T> Extend<&'a T> for NonEmptyVec<T>
where
T: 'a + Copy,
{
#[inline]
fn extend<I: IntoIterator<Item = &'a T>>(&mut self, iter: I) {
self.inner.extend(iter);
}
}
#[cfg(not(no_global_oom_handling))]
#[cfg_attr(doc_cfg, doc(cfg(not(no_global_oom_handling))))]
impl<T> Extend<T> for NonEmptyVec<T> {
#[inline]
fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
self.inner.extend(iter);
}
}
impl<'a, T> IntoIterator for &'a NonEmptyVec<T> {
type Item = &'a T;
type IntoIter = slice::Iter<'a, T>;
#[inline]
fn into_iter(self) -> Self::IntoIter {
self.iter()
}
}
impl<'a, T> IntoIterator for &'a mut NonEmptyVec<T> {
type Item = &'a mut T;
type IntoIter = slice::IterMut<'a, T>;
#[inline]
fn into_iter(self) -> Self::IntoIter {
self.iter_mut()
}
}
impl<T> IntoIterator for NonEmptyVec<T> {
type Item = T;
type IntoIter = vec::IntoIter<T>;
#[inline]
fn into_iter(self) -> Self::IntoIter {
self.inner.into_iter()
}
}
////////////////////////////////////////////////////////////////////////////////
/// Collection equivalence
////////////////////////////////////////////////////////////////////////////////
impl<T, U> PartialEq<VecDeque<U>> for NonEmptyVec<T>
where
T: PartialEq<U>,
{
// This is a workaround since rustlib's PartialEq implementation isn't
// symmetric.
fn eq(&self, other: &VecDeque<U>) -> bool {
if self.inner.len() != other.len() {
return false;
}
let (oa, ob) = other.as_slices();
let (sa, sb) = self.split_at(oa.len());
sa == oa && sb == ob
}
}
impl<T, U> PartialEq<NonEmptyVec<U>> for VecDeque<T>
where
T: PartialEq<U>,
{
fn eq(&self, other: &NonEmptyVec<U>) -> bool {
self == &other.inner
}
}
impl<T, U> PartialEq<NonEmptyVec<U>> for NonEmptyVec<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &NonEmptyVec<U>) -> bool {
self.inner == other.inner
}
}
impl<T, U> PartialEq<Vec<U>> for NonEmptyVec<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &Vec<U>) -> bool {
&self.inner == other
}
}
impl<T, U> PartialEq<NonEmptyVec<U>> for Vec<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &NonEmptyVec<U>) -> bool {
self == &other.inner
}
}
#[cfg(any(feature = "alloc", feature = "std"))]
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T, U> PartialEq<NonEmptySlice<U>> for NonEmptyVec<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &NonEmptySlice<U>) -> bool {
self.as_slice() == other
}
}
#[cfg(any(feature = "alloc", feature = "std"))]
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T, U> PartialEq<NonEmptyVec<U>> for NonEmptySlice<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &NonEmptyVec<U>) -> bool {
self == other.as_slice()
}
}
impl<T, U> PartialEq<[U]> for NonEmptyVec<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &[U]) -> bool {
self.inner == other
}
}
impl<T, U> PartialEq<NonEmptyVec<U>> for [T]
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &NonEmptyVec<U>) -> bool {
self == other.inner
}
}
impl<T, U, const N: usize> PartialEq<[U; N]> for NonEmptyVec<T>
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &[U; N]) -> bool {
self.inner == other
}
}
impl<T, U, const N: usize> PartialEq<NonEmptyVec<U>> for [T; N]
where
T: PartialEq<U>,
{
#[inline]
fn eq(&self, other: &NonEmptyVec<U>) -> bool {
// Workaround for yet another asymmetric PartialEq implementation
self == other.as_slice()
}
}
impl<T> Eq for NonEmptyVec<T> where T: Eq {}
impl<T> PartialOrd for NonEmptyVec<T>
where
T: PartialOrd,
{
#[inline]
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
PartialOrd::partial_cmp(&self.inner, &other.inner)
}
}
impl<T> Ord for NonEmptyVec<T>
where
T: Ord,
{
#[inline]
fn cmp(&self, other: &Self) -> Ordering {
Ord::cmp(&self.inner, &other.inner)
}
}
impl<T> Hash for NonEmptyVec<T>
where
T: Hash,
{
#[inline]
fn hash<H: Hasher>(&self, state: &mut H) {
self.inner.hash(state);
}
}
////////////////////////////////////////////////////////////////////////////////
// NonEmptyVec -> smart pointer holding a head-allocated slice
////////////////////////////////////////////////////////////////////////////////
impl<T> From<NonEmptyVec<T>> for Arc<[T]> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
Arc::from(value.inner)
}
}
impl<T> From<NonEmptyVec<T>> for Box<[T]> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
value.inner.into_boxed_slice()
}
}
impl<'a, T> From<&'a NonEmptyVec<T>> for Cow<'a, [T]>
where
T: Clone,
{
#[inline]
fn from(v: &'a NonEmptyVec<T>) -> Self {
Cow::Borrowed(v)
}
}
impl<T> From<NonEmptyVec<T>> for Rc<[T]> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
Rc::from(value.inner)
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> From<NonEmptyVec<T>> for Arc<NonEmptySlice<T>> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
let arc: Arc<[T]> = Arc::from(value);
let ptr = Arc::into_raw(arc) as *const NonEmptySlice<T>;
unsafe { Arc::from_raw(ptr) }
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> From<NonEmptyVec<T>> for Box<NonEmptySlice<T>> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
value.into_boxed_slice()
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<'a, T> From<&'a NonEmptyVec<T>> for Cow<'a, NonEmptySlice<T>>
where
T: Clone,
{
#[inline]
fn from(v: &'a NonEmptyVec<T>) -> Self {
Cow::Borrowed(v)
}
}
#[cfg_attr(doc_cfg, doc(cfg(any(feature = "alloc", feature = "std"))))]
impl<T> From<NonEmptyVec<T>> for Rc<NonEmptySlice<T>> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
let rc: Rc<[T]> = Rc::from(value);
let ptr = Rc::into_raw(rc) as *const NonEmptySlice<T>;
unsafe { Rc::from_raw(ptr) }
}
}
////////////////////////////////////////////////////////////////////////////////
// NonEmptyVec -> collections
////////////////////////////////////////////////////////////////////////////////
#[cfg(feature = "std")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
impl From<NonEmptyVec<NonZeroU8>> for CString {
#[inline]
fn from(value: NonEmptyVec<NonZeroU8>) -> Self {
CString::from(value.inner)
}
}
impl<T> From<NonEmptyVec<T>> for Vec<T> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
value.inner
}
}
impl<T> From<NonEmptyVec<T>> for VecDeque<T> {
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
VecDeque::from(value.inner)
}
}
impl<T> From<NonEmptyVec<T>> for BinaryHeap<T>
where
T: Ord,
{
#[inline]
fn from(value: NonEmptyVec<T>) -> Self {
BinaryHeap::from(value.inner)
}
}
////////////////////////////////////////////////////////////////////////////////
// Failable conversions: collections -> NonEmptyVec
////////////////////////////////////////////////////////////////////////////////
impl<T> TryFrom<&[T]> for NonEmptyVec<T>
where
T: Clone,
{
type Error = EmptyError;
#[inline]
fn try_from(value: &[T]) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
impl<T> TryFrom<&mut [T]> for NonEmptyVec<T>
where
T: Clone,
{
type Error = EmptyError;
#[inline]
fn try_from(value: &mut [T]) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
impl<'a, T> TryFrom<Cow<'a, [T]>> for NonEmptyVec<T>
where
[T]: ToOwned<Owned = Vec<T>>,
{
type Error = EmptyError;
fn try_from(value: Cow<'a, [T]>) -> Result<Self, Self::Error> {
let vec = value.into_owned();
NonEmptyVec::new(vec)
}
}
impl TryFrom<&str> for NonEmptyVec<u8> {
type Error = EmptyError;
fn try_from(value: &str) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
impl TryFrom<String> for NonEmptyVec<u8> {
type Error = EmptyError;
#[inline]
fn try_from(value: String) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
#[cfg(feature = "std")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
impl TryFrom<CString> for NonEmptyVec<u8> {
type Error = EmptyError;
#[inline]
fn try_from(value: CString) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
impl<T> TryFrom<Vec<T>> for NonEmptyVec<T> {
type Error = EmptyError;
#[inline]
fn try_from(value: Vec<T>) -> Result<Self, Self::Error> {
NonEmptyVec::new(value)
}
}
impl<T> TryFrom<VecDeque<T>> for NonEmptyVec<T> {
type Error = EmptyError;
#[inline]
fn try_from(value: VecDeque<T>) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
impl<T> TryFrom<BinaryHeap<T>> for NonEmptyVec<T> {
type Error = EmptyError;
#[inline]
fn try_from(value: BinaryHeap<T>) -> Result<Self, Self::Error> {
NonEmptyVec::new(value.into())
}
}
////////////////////////////////////////////////////////////////////////////////
/// Failable conversions: non-empty vector -> X
////////////////////////////////////////////////////////////////////////////////
impl<T, const N: usize> TryFrom<NonEmptyVec<T>> for [T; N] {
type Error = NonEmptyVec<T>;
fn try_from(mut value: NonEmptyVec<T>) -> Result<Self, Self::Error> {
if value.inner.len() != N {
return Err(value);
}
// SAFETY: `.set_len(0)` is always sound. Also, the contract of the
// newtype is invalidated, but since it drops here it's no issue.
unsafe { value.inner.set_len(0) };
// SAFETY: A `Vec`'s pointer is always aligned properly, and the
// alignment the array needs is the same as the items. It's already
// known that there's enough items. The items will not double-drop as
// the `set_len` tells the `Vec` not to also drop them.
let array = unsafe { ptr::read(value.as_ptr().cast::<[T; N]>()) };
Ok(array)
}
}
////////////////////////////////////////////////////////////////////////////////
// `io` implementations
////////////////////////////////////////////////////////////////////////////////
#[cfg(feature = "std")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
impl Write for NonEmptyVec<u8> {
#[inline]
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
Write::write(&mut self.inner, buf)
}
#[inline]
fn write_vectored(&mut self, bufs: &[io::IoSlice<'_>]) -> io::Result<usize> {
Write::write_vectored(&mut self.inner, bufs)
}
#[inline]
fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
Write::write_all(&mut self.inner, buf)
}
#[inline]
fn flush(&mut self) -> io::Result<()> {
Write::flush(&mut self.inner)
}
}
////////////////////////////////////////////////////////////////////////////////
// `serde` implementations
////////////////////////////////////////////////////////////////////////////////
#[cfg(feature = "serde")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "serde")))]
impl<T> serde::Serialize for NonEmptyVec<T>
where
T: serde::Serialize,
{
#[inline]
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serde::Serialize::serialize(&self.inner, serializer)
}
}
#[cfg(all(feature = "serde", not(no_global_oom_handling)))]
#[cfg_attr(doc_cfg, doc(cfg(all(feature = "serde", not(no_global_oom_handling)))))]
impl<'de, T> serde::Deserialize<'de> for NonEmptyVec<T>
where
T: serde::Deserialize<'de>,
{
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
let vec: Vec<T> = serde::Deserialize::deserialize(deserializer)?;
NonEmptyVec::new(vec).map_err(|_| {
serde::de::Error::custom("cannot deserialize `NonEmptyVec` from an empty sequence")
})
}
}