bounded_vector/

bounded_vec.rs

#![allow(clippy::let_unit_value)]

use core::fmt;
use std::{
	collections::TryReserveError,
	fmt::Debug,
	ops::{Bound, Deref, DerefMut, RangeBounds, RangeInclusive},
};
use thiserror::Error;

/// Errors used by BoundedVec
#[derive(Error, Debug, PartialEq, Eq, Hash, Clone, Copy)]
pub enum Error {
	#[error("Vector len outside LOW and UPP bounds")]
	/// Vector len doesn't fit LOW and UPP bounds
	OutOfBoundsVec,
}

/// Bounded Vec with minimal (L - lower bound) and maximal (U - upper bound) length
#[derive(PartialEq, Eq, Hash, Clone)]
pub struct BoundedVec<T, const LOW: usize, const UPP: usize>(Vec<T>);

impl<T, const LOW: usize, const UPP: usize> BoundedVec<T, LOW, UPP> {
	#[doc(hidden)]
	pub const VALID_L_U_TEST: () = assert!(LOW <= UPP);
	#[doc(hidden)]
	pub const BOUNDS: RangeInclusive<usize> = LOW..=UPP;

	/// # Safety
	///
	/// This is highly unsafe, due to the number of invariants that aren't
	/// checked:
	///
	/// * `ptr` must have been allocated using the global allocator, such as via
	///   the [`alloc::alloc`] function.
	/// * `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`.
	/// * The first `length` values must be properly initialized values of type `T`.
	/// * `capacity` needs to be the capacity that the pointer was allocated with.
	/// * The allocated size in bytes must be no larger than `isize::MAX`.
	///   See the safety documentation of pointer::offset.
	/// * `length` needs to be in range of upper and lower bounds
	///
	/// These requirements are always upheld by any `ptr` that has been allocated
	/// via `Vec<T>`. Other allocation sources are allowed if the invariants are
	/// upheld.
	///
	/// Violating these may cause problems like corrupting the allocator's
	/// internal data structures. For example it is normally **not** safe
	/// to build a `Vec<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 `Vec<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 `Vec<u8>` it'll be deallocated with alignment 1. To avoid
	/// these issues, it is often preferable to do casting/transmuting using
	/// [`std::slice::from_raw_parts`] instead.
	///
	/// The ownership of `ptr` is effectively transferred to the
	/// `Vec<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.
	///
	/// [`String`]: std::string::String
	/// [`alloc::alloc`]: std::alloc::alloc
	/// [`dealloc`]: std::alloc::GlobalAlloc::dealloc
	///
	#[inline]
	pub unsafe fn from_raw_parts(
		ptr: *mut T,
		length: usize,
		capacity: usize,
	) -> Result<Self, Error> {
		let _ = Self::VALID_L_U_TEST;
		if !Self::BOUNDS.contains(&length) {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(Self(Vec::from_raw_parts(ptr, length, capacity)))
	}

	/// # Safety
	/// This function creates BoundedVec without checking length bounds.
	/// You need to make sure that vec.length() is in LOW..=UPP.
	#[inline]
	pub unsafe fn from_vec_unchecked(vec: Vec<T>) -> BoundedVec<T, LOW, UPP> {
		BoundedVec(vec)
	}

	/// Returns reference to inner Vector
	#[inline]
	pub fn as_vec(&self) -> &Vec<T> {
		&self.0
	}

	/// Returns inner Vector
	#[inline]
	pub fn to_vec(self) -> Vec<T> {
		self.0
	}

	/// # Safety
	///
	/// Vector len must always be in range of upper and lower bounds
	///
	#[inline]
	pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<T> {
		&mut self.0
	}

	/// Reserves capacity for at least `additional` more elements to be inserted
	/// in the given `BoundedVec<T, LOW, UPP>`. 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.
	///
	/// # Panics
	///
	/// Panics if the new capacity exceeds `isize::MAX` _bytes_.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = bvec![1].expect("In range");
	/// vec.reserve(10);
	/// assert!(vec.capacity() >= 11);
	/// ```
	#[inline]
	pub fn reserve(&mut self, additional: usize) {
		self.0.reserve(additional)
	}

	/// Returns the total number of elements the vector can hold without
	/// reallocating.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = BoundedVec::with_capacity(10);
	/// vec.push(42);
	/// assert!(vec.capacity() >= 10);
	/// ```
	#[inline]
	pub fn capacity(&self) -> usize {
		self.0.capacity()
	}

	/// Reserves the minimum capacity for at least `additional` more elements to
	/// be inserted in the given `BoundedVec<T, LOW, UPP>`. 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.
	///
	/// [`reserve`]: BoundedVec::reserve
	///
	/// # Panics
	///
	/// Panics if the new capacity exceeds `isize::MAX` _bytes_.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = bvec![1].expect("In range");
	/// vec.reserve_exact(10);
	/// assert!(vec.capacity() >= 11);
	/// ```
	#[inline]
	pub fn reserve_exact(&mut self, additional: usize) {
		self.0.reserve_exact(additional)
	}

	/// Tries to reserve capacity for at least `additional` more elements to be inserted
	/// in the given `BoundedVec<T, LOW, UPP>`. 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. This method
	/// preserves the contents even if an error occurs.
	///
	/// # Errors
	///
	/// If the capacity overflows, or the allocator reports a failure, then an error
	/// is returned.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	/// use std::collections::TryReserveError;
	///
	/// fn process_data<const SIZE: usize>(data: &[u32; SIZE]) -> Result<BoundedVec<u32, 0, SIZE>, TryReserveError> {
	///     let mut output = BoundedVec::new();
	///
	///     // Pre-reserve the memory, exiting if we can't
	///     output.try_reserve(SIZE)?;
	///
	///     // Now we know this can't OOM in the middle of our complex work
	///     data.iter().for_each(|&val| {
	///         output.push(val * 2 + 5).expect("In range") // very complicated
	///     });
	///
	///     Ok(output)
	/// }
	/// # process_data(&[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.0.try_reserve(additional)
	}

	/// Tries to reserve the minimum capacity for at least `additional`
	/// elements to be inserted in the given `BoundedVec<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`]: BoundedVec::try_reserve
	///
	/// # Errors
	///
	/// If the capacity overflows, or the allocator reports a failure, then an error
	/// is returned.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	/// use std::collections::TryReserveError;
	///
	/// fn process_data<const SIZE: usize>(data: &[u32; SIZE]) -> Result<BoundedVec<u32, 0, SIZE>, TryReserveError> {
	///     let mut output = BoundedVec::new();
	///
	///     // Pre-reserve the memory, exiting if we can't
	///     output.try_reserve_exact(SIZE)?;
	///
	///     // Now we know this can't OOM in the middle of our complex work
	///     data.iter().for_each(|&val| {
	///         output.push(val * 2 + 5).expect("In range") // very complicated
	///     });
	///
	///     Ok(output)
	/// }
	/// # process_data(&[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.0.try_reserve_exact(additional)
	}

	/// Shrinks the capacity of the vector as much as possible.
	///
	/// The behavior of this method depends on the allocator, which may either shrink the vector
	/// in-place or reallocate. The resulting vector might still have some excess capacity, just as
	/// is the case for [`with_capacity`]. See [`Allocator::shrink`] for more details.
	///
	/// [`with_capacity`]: BoundedVec::with_capacity
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = BoundedVec::with_capacity(10);
	/// vec.append(&mut vec![1, 2, 3]);
	/// assert!(vec.capacity() >= 10);
	/// vec.shrink_to_fit();
	/// assert!(vec.capacity() >= 3);
	/// ```
	#[inline]
	pub fn shrink_to_fit(&mut self) {
		self.0.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.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = BoundedVec::with_capacity(10);
	/// vec.append(&mut vec![1, 2, 3]);
	/// vec.shrink_to(4);
	/// assert!(vec.capacity() >= 4);
	/// vec.shrink_to(0);
	/// assert!(vec.capacity() >= 3);
	/// ```
	#[inline]
	pub fn shrink_to(&mut self, min_capacity: usize) {
		self.0.shrink_to(min_capacity);
	}

	/// Converts the vector into [`Box<[T]>`][owned slice].
	///
	/// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].
	///
	/// [owned slice]: Box
	/// [`shrink_to_fit`]: Vec::shrink_to_fit
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let v: BoundedVec<i32, 0, 10> = bvec![1, 2, 3].expect("In range");
	/// let slice = v.into_boxed_slice();
	/// ```
	///
	/// Any excess capacity is removed:
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	/// let mut vec: BoundedVec<i32, 0, 10> = BoundedVec::with_capacity(10);
	/// vec.append(&mut vec![1, 2, 3]);
	///
	/// assert!(vec.capacity() >= 10);
	/// let slice = vec.into_boxed_slice();
	/// assert_eq!(slice.into_vec().capacity(), 3);
	/// ```
	#[inline]
	pub fn into_boxed_slice(self) -> Box<[T]> {
		self.0.into_boxed_slice()
	}

	/// Shortens the vector, keeping the first `len` elements and dropping
	/// the rest.
	///
	/// If `len` is greater or equal to the vector's current length, this has
	/// no effect.
	///
	/// Note that this method has no effect on the allocated capacity
	/// of the vector.
	///
	/// # Examples
	///
	/// Truncating a five element vector to two elements:
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = bvec![1, 2, 3, 4, 5].expect("In range");
	/// vec.truncate(2).expect("In range");
	/// assert_eq!(vec.as_slice(), &[1, 2][..]);
	/// ```
	///
	/// No truncation occurs when `len` is greater than the vector's current
	/// length:
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = bvec![1, 2, 3].expect("In range");
	/// vec.truncate(8).expect("In range");
	/// assert_eq!(vec.as_slice(), &[1, 2, 3][..]);
	/// ```
	///
	/// Truncating when `len == 0` is equivalent to calling the [`clear`]
	/// method.
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = bvec![1, 2, 3].expect("In range");
	/// vec.truncate(0).expect("In range");
	/// assert!(vec.is_empty());
	/// ```
	///
	/// When length is smaller than LOW bound truncate returns Error
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<i32, 2, 10> = bvec![1, 2, 3].expect("In range");
	/// assert_eq!(vec.truncate(1), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2, 3][..]);
	/// ```
	///
	/// [`clear`]: Vec::clear
	#[inline]
	pub fn truncate(&mut self, length: usize) -> Result<(), Error> {
		if length < LOW {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.truncate(length);
		Ok(())
	}

	/// Extracts a slice containing the entire vector.
	///
	/// Equivalent to `&s[..]`.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	/// use std::io::{self, Write};
	///
	/// let buffer: BoundedVec<u8, 0, 10> = bvec![1, 2, 3, 5, 8].expect("In range");
	/// io::sink().write(buffer.as_slice()).unwrap();
	/// ```
	#[inline]
	pub fn as_slice(&self) -> &[T] {
		self.0.as_slice()
	}

	/// 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.
	///
	/// The caller must ensure that the vector outlives the pointer this
	/// function returns, or else it will end up dangling.
	/// Modifying the vector may cause its buffer to be reallocated,
	/// which would also make any pointers to it invalid.
	///
	/// The caller must also ensure that the memory the pointer (non-transitively) points to
	/// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer
	/// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`].
	///
	/// This method guarantees that for the purpose of the aliasing model, this method
	/// does not materialize a reference to the underlying slice, and thus the returned pointer
	/// will remain valid when mixed with other calls to [`as_ptr`], [`as_mut_ptr`].
	/// Note that calling other methods that materialize mutable references to the slice,
	/// or mutable references to specific elements you are planning on accessing through this pointer,
	/// as well as writing to those elements, may still invalidate this pointer.
	/// See the second example below for how this guarantee can be used.
	///
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let x: BoundedVec<i32,0,10> = bvec![1, 2, 4].expect("In range");
	/// let x_ptr = x.as_ptr();
	///
	/// unsafe {
	///     for i in 0..x.len() {
	///         assert_eq!(*x_ptr.add(i), 1 << i);
	///     }
	/// }
	/// ```
	///
	/// Due to the aliasing guarantee, the following code is legal:
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// unsafe {
	///     let mut v:BoundedVec<i32,0,10> = bvec![0, 1, 2].expect("In range");
	///     let ptr1 = v.as_ptr();
	///     let _ = ptr1.read();
	///     let ptr2 = v.as_mut_ptr().offset(2);
	///     ptr2.write(2);
	///     // Notably, the write to `ptr2` did *not* invalidate `ptr1`
	///     // because it mutated a different element:
	///     let _ = ptr1.read();
	/// }
	/// ```
	///
	/// [`as_mut_ptr`]: Vec::as_mut_ptr
	/// [`as_ptr`]: Vec::as_ptr
	#[inline]
	pub fn as_ptr(&self) -> *const T {
		self.0.as_ptr()
	}

	/// Extracts a mutable slice of the entire vector.
	///
	/// Equivalent to `&mut s[..]`.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	/// use std::io::{self, Read};
	///
	/// let mut buffer: BoundedVec<u8, 0, 10> = bvec![0; 3].expect("In range");
	/// io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();
	/// ```
	#[inline]
	pub fn as_mut_slice(&mut self) -> &mut [T] {
		self.0.as_mut_slice()
	}

	/// Returns a raw mutable pointer to the vector's buffer, or a dangling
	/// raw pointer valid for zero sized reads if the vector didn't allocate.
	///
	/// The caller must ensure that the vector outlives the pointer this
	/// function returns, or else it will end up dangling.
	/// Modifying the vector may cause its buffer to be reallocated,
	/// which would also make any pointers to it invalid.
	///
	/// This method guarantees that for the purpose of the aliasing model, this method
	/// does not materialize a reference to the underlying slice, and thus the returned pointer
	/// will remain valid when mixed with other calls to [`as_ptr`], [`as_mut_ptr`].
	/// Note that calling other methods that materialize references to the slice,
	/// or references to specific elements you are planning on accessing through this pointer,
	/// may still invalidate this pointer.
	/// See the second example below for how this guarantee can be used.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// // Allocate vector big enough for 4 elements.
	/// let size = 4;
	/// let mut x: BoundedVec<i32, 0, 10> = BoundedVec::with_capacity(size);
	/// let x_ptr = x.as_mut_ptr();
	///
	/// // Initialize elements via raw pointer writes, then set length.
	/// unsafe {
	///     for i in 0..size {
	///         *x_ptr.add(i) = i as i32;
	///     }
	///     x.set_len(size);
	/// }
	/// assert_eq!(&*x, &[0, 1, 2, 3]);
	/// ```
	///
	/// Due to the aliasing guarantee, the following code is legal:
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// unsafe {
	///     let mut v: BoundedVec<i32, 0, 10> = bvec![0].expect("In range");
	///     let ptr1 = v.as_mut_ptr();
	///     ptr1.write(1);
	///     let ptr2 = v.as_mut_ptr();
	///     ptr2.write(2);
	///     // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
	///     ptr1.write(3);
	/// }
	/// ```
	///
	/// [`as_mut_ptr`]: Vec::as_mut_ptr
	/// [`as_ptr`]: Vec::as_ptr
	/// [`as_non_null`]: Vec::as_non_null
	#[inline]
	pub fn as_mut_ptr(&mut self) -> *mut T {
		self.0.as_mut_ptr()
	}

	/// # Safety
	///
	/// - `new_len` must be less than or equal to [`capacity()`].
	/// - `new_len` must be in range of upper and lower bounds
	/// - The elements at `old_len..new_len` must be initialized.
	///
	/// [`capacity()`]: Vec::capacity
	///
	#[inline]
	pub unsafe fn set_len(&mut self, new_len: usize) -> Result<(), Error> {
		self.0.set_len(new_len);
		Ok(())
	}

	/// 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 of the remaining elements, but is *O*(1).
	/// If you need to preserve the element order, use [`remove`] instead.
	///
	/// Returns error if len after removal would be out of bounds
	///
	/// [`remove`]: BoundedVec::remove
	///
	/// # Panics
	///
	/// Panics if `index` is out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut v: BoundedVec<&str, 2, 10> = bvec!["foo", "bar", "baz", "qux"].expect("In range");
	///
	/// assert_eq!(v.swap_remove(1), Ok("bar"));
	/// assert_eq!(v.as_slice(), &["foo", "qux", "baz"][..]);
	///
	/// assert_eq!(v.swap_remove(0), Ok("foo"));
	/// assert_eq!(v.as_slice(), &["baz", "qux"][..]);
	///
	/// assert_eq!(v.swap_remove(0), Err(Error::OutOfBoundsVec));
	/// assert_eq!(v.as_slice(), &["baz", "qux"][..]);
	/// ```
	#[inline]
	pub fn swap_remove(&mut self, index: usize) -> Result<T, Error> {
		if self.len() <= LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self.0.swap_remove(index))
	}

	/// Inserts an element at position `index` within the vector, shifting all
	/// elements after it to the right.
	///
	/// Returns error if len after inserting would be out of bounds.
	///
	/// # Panics
	///
	/// Panics if `index > len`.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<char, 0, 5> = bvec!['a', 'b', 'c'].expect("In range");
	/// vec.insert(1, 'd').expect("In range");
	/// assert_eq!(vec.as_slice(), &['a', 'd', 'b', 'c'][..]);
	/// vec.insert(4, 'e').expect("In range");
	/// assert_eq!(vec.as_slice(), &['a', 'd', 'b', 'c', 'e'][..]);
	/// assert_eq!(vec.insert(4, 'e'), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &['a', 'd', 'b', 'c', 'e'][..]);
	/// ```
	///
	/// # Time complexity
	///
	/// Takes *O*([`Vec::len`]) time. All items after the insertion index must be
	/// shifted to the right. In the worst case, all elements are shifted when
	/// the insertion index is 0.
	#[inline]
	pub fn insert(&mut self, index: usize, element: T) -> Result<(), Error> {
		if self.len() >= UPP {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.insert(index, element);
		Ok(())
	}

	/// Removes and returns the element at position `index` within the vector,
	/// shifting all elements after it to the left.
	///
	/// Returns error if len after removing would be out of bounds.
	///
	/// Note: 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`] instead.
	///
	/// [`swap_remove`]: BoundedVec::swap_remove
	///
	/// # Panics
	///
	/// Panics if `index` is out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut v: BoundedVec<char, 2, 10> = bvec!['a', 'b', 'c'].expect("In range");
	/// assert_eq!(v.remove(1), Ok('b'));
	/// assert_eq!(v.as_slice(), &['a', 'c'][..]);
	/// assert_eq!(v.remove(1), Err(Error::OutOfBoundsVec));
	/// assert_eq!(v.as_slice(), &['a', 'c'][..]);
	/// ```
	#[inline]
	pub fn remove(&mut self, index: usize) -> Result<T, Error> {
		if self.len() <= LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self.0.remove(index))
	}

	/// 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.
	///
	/// Returns error if len after removing would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let vec: BoundedVec<i32, 1, 10> = bvec![1, 2, 3, 4].expect("In range");
	/// let vec = vec.retain(|&x| x % 2 == 0).expect("In range");
	/// assert_eq!(vec.as_slice(), &[2, 4][..]);
	/// assert_eq!(vec.retain(|&x| x % 2 == 1), Err(Error::OutOfBoundsVec));
	/// ```
	///
	/// Because the elements are visited exactly once in the original order,
	/// external state may be used to decide which elements to keep.
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let vec: BoundedVec<i32, 0, 10> = bvec![1, 2, 3, 4, 5].expect("In range");
	/// let keep = [false, true, true, false, true];
	/// let mut iter = keep.iter();
	/// let vec = vec.retain(|_| *iter.next().unwrap()).expect("In range");
	/// assert_eq!(vec.as_slice(), &[2, 3, 5][..]);
	/// ```
	#[inline]
	pub fn retain<F>(mut self, f: F) -> Result<Self, Error>
	where
		F: FnMut(&T) -> bool,
	{
		self.0.retain(f);
		if self.len() < LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self)
	}

	/// 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.
	///
	/// Returns error if len after removing would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let vec: BoundedVec<i32, 1, 10> = bvec![1, 2, 3, 4].expect("In range");
	/// let vec = vec.retain_mut(|x| if *x <= 3 {
	///     *x += 1;
	///     true
	/// } else {
	///     false
	/// }).expect("In range");
	/// assert_eq!(vec.as_slice(), &[2, 3, 4][..]);
	/// assert_eq!(vec.retain(|_| false), Err(Error::OutOfBoundsVec))
	/// ```
	#[inline]
	pub fn retain_mut<F>(mut self, f: F) -> Result<Self, Error>
	where
		F: FnMut(&mut T) -> bool,
	{
		self.0.retain_mut(f);
		if self.len() < LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self)
	}

	/// 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.
	///
	/// Returns error if len after removing would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let vec: BoundedVec<i32, 2, 10> = bvec![10, 20, 21, 30, 20].expect("In range");
	/// let vec = vec.dedup_by_key(|i| *i / 10).expect("In range");
	/// assert_eq!(vec.as_slice(), &[10, 20, 30, 20][..]);
	/// assert_eq!(vec.dedup_by_key(|i| *i/100), Err(Error::OutOfBoundsVec));
	/// ```
	#[inline]
	pub fn dedup_by_key<F, K>(mut self, key: F) -> Result<Self, Error>
	where
		F: FnMut(&mut T) -> K,
		K: PartialEq,
	{
		self.0.dedup_by_key(key);
		if self.len() < LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self)
	}

	/// 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.
	///
	/// Returns error if len after removing would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let vec: BoundedVec<&str, 2, 10> = bvec!["foo", "bar", "Bar", "baz", "bar"].expect("In range");
	/// let vec = vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b)).expect("In range");
	/// assert_eq!(vec.as_slice(), &["foo", "bar", "baz", "bar"][..]);
	/// assert_eq!(vec.dedup_by(|_, _| true), Err(Error::OutOfBoundsVec));
	/// ```
	#[inline]
	pub fn dedup_by<F>(mut self, same_bucket: F) -> Result<Self, Error>
	where
		F: FnMut(&mut T, &mut T) -> bool,
	{
		self.0.dedup_by(same_bucket);
		if self.len() < LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self)
	}

	/// Appends an element to the back of a collection.
	///
	/// Returns error if len after pushing would be out of bounds.
	///
	/// # Panics
	///
	/// Panics if the new capacity exceeds `isize::MAX` _bytes_.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<i32, 0, 3> = bvec![1, 2].expect("In range");
	/// vec.push(3).expect("In range");
	/// assert_eq!(vec.as_slice(), &[1, 2, 3][..]);
	/// assert_eq!(vec.push(4), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2, 3][..]);
	/// ```
	///
	/// # Time complexity
	///
	/// Takes amortized *O*(1) time. If the vector's length would exceed its
	/// capacity after the push, *O*(*capacity*) time is taken to copy the
	/// vector's elements to a larger allocation. This expensive operation is
	/// offset by the *capacity* *O*(1) insertions it allows.
	#[inline]
	pub fn push(&mut self, value: T) -> Result<(), Error> {
		if self.len() >= UPP {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.push(value);
		Ok(())
	}

	/// Removes the last element from a vector and returns it, or [`Error::OutOfBoundsVec`] if size
	/// after removal size would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<i32, 2, 10> = bvec![1, 2, 3].expect("In range");
	/// assert_eq!(vec.pop(), Ok(3));
	/// assert_eq!(vec.as_slice(), &[1, 2][..]);
	/// assert_eq!(vec.pop(), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2][..]);
	/// ```
	///
	/// # Time complexity
	///
	/// Takes *O*(1) time.
	#[inline]
	pub fn pop(&mut self) -> Result<T, Error> {
		if self.len() <= LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self.0.pop().expect("Checked before"))
	}

	/// Moves all the elements of `other` into `self`, leaving `other` empty.
	///
	/// Returns error if len after pushing would be out of bounds.
	///
	/// # Panics
	///
	/// Panics if the new capacity exceeds `isize::MAX` _bytes_.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<i32, 2, 6> = bvec![1, 2, 3].expect("In range");
	/// let mut vec2 = vec![4, 5, 6];
	/// vec.append(&mut vec2).expect("In range");
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 4, 5, 6][..]);
	/// assert_eq!(vec2, []);
	/// assert_eq!(vec.append(&mut vec![7]), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 4, 5, 6][..]);
	/// ```
	#[inline]
	pub fn append(&mut self, vec: &mut Vec<T>) -> Result<(), Error> {
		if self.len() + vec.len() > UPP {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.append(vec);
		Ok(())
	}

	/// Returns the number of elements in the vector, also referred to
	/// as its 'length'.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let a: BoundedVec<i32, 0, 10> = bvec![1, 2, 3].expect("In range");
	/// assert_eq!(a.len(), 3);
	/// ```
	#[inline]
	pub fn len(&self) -> usize {
		if LOW == UPP {
			LOW
		} else {
			self.0.len()
		}
	}

	/// Returns `true` if the vector contains no elements.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// let mut v: BoundedVec<i32, 0, 10> = BoundedVec::new();
	/// assert!(v.is_empty());
	///
	/// v.push(1).expect("In range");
	/// assert!(!v.is_empty());
	/// ```
	#[inline]
	pub fn is_empty(&self) -> bool {
		if UPP == 0 {
			true
		} else {
			self.0.is_empty()
		}
	}

	/// 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.
	///
	/// Returns error if len after splitting would be out of bounds.
	///
	/// - If you want to take ownership of the entire contents and capacity of
	///   the vector, see [`mem::take`] or [`mem::replace`].
	/// - If you don't need the returned vector at all, see [`Vec::truncate`].
	///
	/// # Panics
	///
	/// Panics if `at > len`.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<char, 1, 10> = bvec!['a', 'b', 'c'].expect("In range");
	/// let vec2 = vec.split_off(1).expect("In range");
	/// assert_eq!(vec.as_slice(), &['a'][..]);
	/// assert_eq!(vec2, ['b', 'c']);
	/// assert_eq!(vec.split_off(0), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &['a'][..]);
	/// ```
	#[inline]
	pub fn split_off(&mut self, at: usize) -> Result<Vec<T>, Error> {
		if at < LOW {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(self.0.split_off(at))
	}

	/// Resizes the `BoundedVec` in-place so that `len` is equal to `new_len`.
	///
	/// If `new_len` is greater than `len`, the `BoundedVec` 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 `Vec` in the order they have been generated.
	///
	/// If `new_len` is less than `len`, the `BoundedVec` is simply truncated.
	///
	/// This method uses a closure to create new values on every push. If
	/// you'd rather [`Clone`] a given value, use [`BoundedVec::resize`]. If you
	/// want to use the [`Default`] trait to generate values, you can
	/// pass [`Default::default`] as the second argument.
	///
	/// Returns error if len after resizing would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<i32, 1, 5> = bvec![1, 2, 3].expect("In range");
	/// vec.resize_with(5, Default::default).expect("In range");
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 0, 0][..]);
	/// assert_eq!(vec.resize_with(6, Default::default), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 0, 0][..]);
	/// assert_eq!(vec.resize_with(0, Default::default), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 0, 0][..]);
	///
	/// let mut vec: BoundedVec<i32, 0, 10> = bvec![];
	/// let mut p = 1;
	/// vec.resize_with(4, || { p *= 2; p }).expect("In range");
	/// assert_eq!(vec.as_slice(), &[2, 4, 8, 16][..]);
	/// ```
	#[inline]
	pub fn resize_with<F>(&mut self, new_len: usize, f: F) -> Result<(), Error>
	where
		F: FnMut() -> T,
	{
		if !Self::BOUNDS.contains(&new_len) {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.resize_with(new_len, f);
		Ok(())
	}

	/// Converts BoundedVec into BoundedVec with less strict bounds
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let vec: BoundedVec<i32, 3, 3> = bvec![1,2,3].expect("In range");
	/// let vec: BoundedVec<i32, 0, 10> = vec.into_bounded_vec();
	/// ```
	#[inline]
	pub fn into_bounded_vec<const LOW2: usize, const UPP2: usize>(
		self,
	) -> BoundedVec<T, LOW2, UPP2> {
		let _ = const { assert!(LOW2 <= LOW) };
		let _ = const { assert!(UPP2 >= UPP) };

		unsafe { BoundedVec::<T, LOW2, UPP2>::from_vec_unchecked(self.to_vec()) }
	}

	/// Converts BoundedVec into other BoundedVec
	///
	/// This method returns error if element count doesn't fit new bounds
	///
	/// # Examples
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let vec: BoundedVec<i32, 0, 10> = bvec![1,2,3].expect("In range");
	/// let vec: BoundedVec<i32, 3, 3> = vec.try_into_bounded_vec().expect("In range");
	/// assert_eq!(vec.try_into_bounded_vec::<4, 4>(), Err(Error::OutOfBoundsVec))
	/// ```
	#[inline]
	pub fn try_into_bounded_vec<const LOW2: usize, const UPP2: usize>(
		self,
	) -> Result<BoundedVec<T, LOW2, UPP2>, Error> {
		if LOW2 <= LOW && UPP2 >= UPP {
			return Ok(unsafe { BoundedVec::<T, LOW2, UPP2>::from_vec_unchecked(self.to_vec()) });
		}

		BoundedVec::try_from(self.to_vec())
	}
}

impl<T: Clone, const LOW: usize, const UPP: usize> BoundedVec<T, LOW, UPP> {
	#[doc(hidden)]
	#[inline]
	pub fn from_elem(elem: T, n: usize) -> Result<Self, Error> {
		if !Self::BOUNDS.contains(&n) {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(Self(vec![elem; n]))
	}

	/// Resizes the `BoundedVec` in-place so that `len` is equal to `new_len`.
	///
	/// If `new_len` is greater than `len`, the `BoundedVec` is extended by the
	/// difference, with each additional slot filled with `value`.
	/// If `new_len` is less than `len`, the `BoundedVec` 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 [`BoundedVec::resize_with`].
	/// If you only need to resize to a smaller size, use [`BoundedVec::truncate`].
	///
	/// This method returns error if new bound doesn't fit bounds
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<&str, 0, 3> = bvec!["hello"].expect("In range");
	/// vec.resize(3, "world").expect("In range");
	/// assert_eq!(vec.as_slice(), &["hello", "world", "world"][..]);
	/// assert_eq!(vec.resize(4, "world"), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &["hello", "world", "world"][..]);
	///
	/// let mut vec: BoundedVec<char, 2, 10> = bvec!['a', 'b', 'c', 'd'].expect("In range");
	/// vec.resize(2, '_');
	/// assert_eq!(vec.as_slice(), &['a', 'b'][..]);
	/// assert_eq!(vec.resize(1, '_'), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &['a', 'b'][..]);
	/// ```
	#[inline]
	pub fn resize(&mut self, new_len: usize, value: T) -> Result<(), Error> {
		if !Self::BOUNDS.contains(&new_len) {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.resize(new_len, value);
		Ok(())
	}

	/// Clones and appends all elements in a slice to the `BoundedVec`.
	///
	/// Iterates over the slice `other`, clones each element, and then appends
	/// it to this `BoundedVec`. The `other` slice is traversed in-order.
	///
	/// Returns error if len after extending would be out of bounds.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut vec: BoundedVec<i32, 0, 5> = bvec![1].expect("In range");
	/// vec.extend_from_slice(&[2, 3, 4]).expect("In range");
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 4][..]);
	/// assert_eq!(vec.extend_from_slice(&[2, 3]), Err(Error::OutOfBoundsVec));
	/// assert_eq!(vec.as_slice(), &[1, 2, 3, 4][..]);
	/// ```
	#[inline]
	pub fn extend_from_slice(&mut self, other: &[T]) -> Result<(), Error> {
		if self.len() + other.len() > UPP {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.extend_from_slice(other);
		Ok(())
	}

	/// Given a range `src`, clones a slice of elements in that range and appends it to the end.
	///
	/// `src` must be a range that can form a valid subslice of the `BoundedVec`.
	///
	/// Returns error if len after extending would be out of bounds.
	///
	/// # Panics
	///
	/// Panics if starting index is greater than the end index
	/// or if the index is greater than the length of the vector.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec, Error};
	///
	/// let mut characters: BoundedVec<char, 0, 10> = bvec!['a', 'b', 'c', 'd', 'e'].expect("In range");
	/// characters.extend_from_within(2..).expect("In range");;
	/// assert_eq!(characters.as_slice(), &['a', 'b', 'c', 'd', 'e', 'c', 'd', 'e'][..]);
	///
	/// let mut numbers: BoundedVec<i32, 0, 10> = bvec![0, 1, 2, 3, 4].expect("In range");
	/// numbers.extend_from_within(..2).expect("In range");
	/// assert_eq!(numbers.as_slice(), &[0, 1, 2, 3, 4, 0, 1][..]);
	///
	/// let mut strings: BoundedVec<String, 0, 6> = bvec![String::from("hello"), String::from("world"), String::from("!")].expect("In range");
	/// strings.extend_from_within(1..=2);
	/// assert_eq!(strings.as_slice(), &["hello", "world", "!", "world", "!"][..]);
	/// assert_eq!(strings.extend_from_within(1..=2), Err(Error::OutOfBoundsVec));
	/// assert_eq!(strings.as_slice(), &["hello", "world", "!", "world", "!"][..]);
	/// ```
	pub fn extend_from_within<R>(&mut self, src: R) -> Result<(), Error>
	where
		R: RangeBounds<usize>,
	{
		let start = match src.start_bound() {
			Bound::Unbounded => 0,
			Bound::Excluded(v) => v + 1,
			Bound::Included(v) => *v,
		};

		let end = match src.end_bound() {
			Bound::Unbounded => self.len(),
			Bound::Excluded(v) => *v,
			Bound::Included(v) => v + 1,
		};

		if start > end {
			panic!("Range index starts at {start} but ends at {end}")
		}

		if end > self.len() {
			panic!("Range end outside vector")
		}

		let new_len = end - start + self.len();
		if new_len > UPP {
			return Err(Error::OutOfBoundsVec);
		}

		self.0.extend_from_within(src);
		if !Self::BOUNDS.contains(&self.len()) {
			panic!(
				"The length of array({}) is outside LOW and UPP bounds",
				self.len()
			)
		}

		Ok(())
	}
}

impl<T, const UPP: usize> BoundedVec<T, 0, UPP> {
	/// Constructs a new, empty `BoundedVec<T, LOW, UPP>`.
	///
	/// The vector will not allocate until elements are pushed onto it.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// let vec: BoundedVec<i32, 0, 10> = BoundedVec::new();
	/// ```
	#[inline]
	pub const fn new() -> Self {
		let _ = Self::VALID_L_U_TEST;
		Self(Vec::new())
	}

	/// Constructs a new, empty `BoundedVec<T, LOW, UPP>` with at least the specified capacity.
	///
	/// The vector will be able to hold at least `capacity` elements without
	/// reallocating. This method is allowed to allocate for more elements than
	/// `capacity`. If `capacity` is zero, the vector will not allocate.
	///
	/// It is important to note that although the returned vector has the
	/// minimum *capacity* specified, the vector will have a zero *length*. For
	/// an explanation of the difference between length and capacity, see
	/// *[Capacity and reallocation]*.
	///
	/// If it is important to know the exact allocated capacity of a `Vec`,
	/// always use the [`capacity`] method after construction.
	///
	/// For `BoundedVec<T, LOW, UPP>` where `T` is a zero-sized type, there will be no allocation
	/// and the capacity will always be `usize::MAX`.
	///
	/// [Capacity and reallocation]: #capacity-and-reallocation
	/// [`capacity`]: BoundedVec::capacity
	///
	/// # Panics
	///
	/// Panics if the new capacity exceeds `isize::MAX` _bytes_.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::BoundedVec;
	///
	/// let mut vec: BoundedVec<i32, 0, 11> = BoundedVec::with_capacity(10);
	///
	/// // The vector contains no items, even though it has capacity for more
	/// assert_eq!(vec.len(), 0);
	/// assert!(vec.capacity() >= 10);
	///
	/// // These are all done without reallocating...
	/// for i in 0..10 {
	///     vec.push(i).expect("In range");
	/// }
	/// assert_eq!(vec.len(), 10);
	/// assert!(vec.capacity() >= 10);
	///
	/// // ...but this may make the vector reallocate
	/// vec.push(11).expect("In range");
	/// assert_eq!(vec.len(), 11);
	/// assert!(vec.capacity() >= 11);
	///
	/// // A vector of a zero-sized type will always over-allocate, since no
	/// // allocation is necessary
	/// let vec_units: BoundedVec<(), 0, 10> = BoundedVec::with_capacity(10);
	/// assert_eq!(vec_units.capacity(), usize::MAX);
	/// ```
	#[inline]
	pub fn with_capacity(capacity: usize) -> Self {
		let _ = Self::VALID_L_U_TEST;
		Self(Vec::with_capacity(capacity))
	}

	/// Clears the vector, removing all values.
	///
	/// Note that this method has no effect on the allocated capacity
	/// of the vector.
	///
	/// # Examples
	///
	/// ```
	/// use bounded_vector::{BoundedVec, bvec};
	///
	/// let mut v: BoundedVec<i32, 0, 10> = bvec![1, 2, 3].expect("In range");
	///
	/// v.clear();
	///
	/// assert!(v.is_empty());
	/// ```
	#[inline]
	pub fn clear(&mut self) {
		self.0.clear()
	}
}

impl<T, const UPP: usize> Default for BoundedVec<T, 0, UPP> {
	fn default() -> Self {
		Self::new()
	}
}

impl<T, const LOW: usize, const UPP: usize> TryFrom<Vec<T>> for BoundedVec<T, LOW, UPP> {
	type Error = Error;
	fn try_from(value: Vec<T>) -> Result<Self, Self::Error> {
		let _ = Self::VALID_L_U_TEST;
		if !Self::BOUNDS.contains(&value.len()) {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(Self(value))
	}
}

impl<T, const LOW: usize, const UPP: usize> TryFrom<Box<[T]>> for BoundedVec<T, LOW, UPP> {
	type Error = Error;
	fn try_from(value: Box<[T]>) -> Result<Self, Self::Error> {
		let _ = Self::VALID_L_U_TEST;
		if !Self::BOUNDS.contains(&value.len()) {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(Self(value.into()))
	}
}

impl<T, const LOW: usize, const UPP: usize> From<BoundedVec<T, LOW, UPP>> for Vec<T> {
	fn from(value: BoundedVec<T, LOW, UPP>) -> Self {
		let _ = BoundedVec::<T, LOW, UPP>::VALID_L_U_TEST;
		value.0
	}
}

impl<T, const LOW: usize, const UPP: usize, const N: usize> TryFrom<[T; N]>
	for BoundedVec<T, LOW, UPP>
{
	type Error = Error;
	fn try_from(value: [T; N]) -> Result<Self, Self::Error> {
		let _ = Self::VALID_L_U_TEST;
		if !Self::BOUNDS.contains(&N) {
			return Err(Error::OutOfBoundsVec);
		}

		Ok(Self(value.into()))
	}
}

impl<T, const LOW: usize, const UPP: usize> AsRef<Vec<T>> for BoundedVec<T, LOW, UPP> {
	fn as_ref(&self) -> &Vec<T> {
		&self.0
	}
}

impl<T, const LOW: usize, const UPP: usize> Deref for BoundedVec<T, LOW, UPP> {
	type Target = [T];
	fn deref(&self) -> &Self::Target {
		&self.0
	}
}

impl<T, const LOW: usize, const UPP: usize> DerefMut for BoundedVec<T, LOW, UPP> {
	fn deref_mut(&mut self) -> &mut Self::Target {
		&mut self.0
	}
}

impl<T: Debug, const LOW: usize, const UPP: usize> Debug for BoundedVec<T, LOW, UPP> {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		fmt::Debug::fmt(&*self.0, f)
	}
}

#[cfg(test)]
mod tests {
	use crate::bvec;

	use super::*;

	const fn err<T>() -> Result<T, Error> {
		Err(Error::OutOfBoundsVec)
	}

	#[test]
	fn try_into_bounded_vec() {
		let bvec: BoundedVec<_, 1, 5> = bvec![1, 2, 3, 4].unwrap();
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<1, 5>(),
			Ok(bvec![1, 2, 3, 4].unwrap())
		);
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<4, 4>(),
			Ok(bvec![1, 2, 3, 4].unwrap())
		);
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<3, 5>(),
			Ok(bvec![1, 2, 3, 4].unwrap())
		);
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<0, 5>(),
			Ok(bvec![1, 2, 3, 4].unwrap())
		);
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<1, 4>(),
			Ok(bvec![1, 2, 3, 4].unwrap())
		);
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<0, 6>(),
			Ok(bvec![1, 2, 3, 4].unwrap())
		);
		assert_eq!(
			bvec.clone().try_into_bounded_vec::<1, 3>(),
			Err(Error::OutOfBoundsVec)
		);
		assert_eq!(
			bvec.try_into_bounded_vec::<5, 5>(),
			Err(Error::OutOfBoundsVec)
		);
	}

	#[test]
	fn format() {
		let bvec: BoundedVec<_, 0, 10> = bvec![1, 2, 3].unwrap();
		assert_eq!("[1, 2, 3]", format!("{:?}", bvec));
	}

	#[test]
	fn format_hash() {
		let bvec: BoundedVec<_, 0, 10> = bvec![1, 2, 3].unwrap();
		assert_eq!("[\n    1,\n    2,\n    3,\n]", format!("{:#?}", bvec));
	}

	#[test]
	fn try_from_array() {
		let bounded_vec = BoundedVec::<_, 2, 3>::try_from([1, 2, 3]).unwrap();
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());

		let bounded_vec = BoundedVec::<_, 1, 2>::try_from([1, 2, 3]);
		assert_eq!(err(), bounded_vec);
	}

	#[test]
	fn try_from_box_array() {
		let bounded_vec =
			BoundedVec::<_, 2, 3>::try_from(vec![1, 2, 3].into_boxed_slice()).unwrap();
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());

		let bounded_vec = BoundedVec::<_, 1, 2>::try_from(vec![1, 2, 3].into_boxed_slice());
		assert_eq!(err(), bounded_vec);
	}

	#[test]
	fn try_from_vec() {
		let bounded_vec = BoundedVec::<_, 2, 3>::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());

		let bounded_vec = BoundedVec::<_, 1, 2>::try_from(vec![1, 2, 3]);
		assert_eq!(err(), bounded_vec);
	}

	#[test]
	fn new() {
		assert_eq!(Vec::<()>::new(), BoundedVec::<(), 0, 0>::new().to_vec());
	}

	#[test]
	fn with_capacity() {
		assert_eq!(
			BoundedVec::<(), 0, 0>::new(),
			BoundedVec::<(), 0, 0>::with_capacity(0)
		);
	}

	#[test]
	fn truncate() {
		let mut bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.truncate(2).unwrap();
		assert_eq!(vec![1, 2], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.truncate(1));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec())
	}

	#[test]
	fn swap_remove() {
		let mut bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(Ok(1), bounded_vec.swap_remove(0));
		assert_eq!(vec![3, 2], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<i32, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.swap_remove(0));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());
	}

	#[test]
	fn insert() {
		let mut bounded_vec: BoundedVec<i32, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.insert(2, 20).unwrap();
		assert_eq!(vec![1, 2, 20, 3], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.insert(3, 4));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());
	}

	#[test]
	fn remove() {
		let mut bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(Ok(2), bounded_vec.remove(1));
		assert_eq!(vec![1, 3], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<i32, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.remove(1));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());
	}

	#[test]
	fn retain() {
		let bounded_vec: BoundedVec<i32, 1, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		let bounded_vec = bounded_vec.retain(|x| *x == 3).unwrap();
		assert_eq!(vec![3], bounded_vec.to_vec());

		let bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.retain(|x| *x == 2));
	}

	#[test]
	fn retain_mut() {
		let bounded_vec: BoundedVec<i32, 1, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		let bounded_vec = bounded_vec
			.retain_mut(|x| {
				*x *= 2;
				*x == 6
			})
			.unwrap();

		assert_eq!(vec![6], bounded_vec.to_vec());

		let bounded_vec: BoundedVec<i32, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(
			err(),
			bounded_vec.retain_mut(|x| {
				*x *= 2;
				*x == 6
			})
		)
	}

	#[test]
	fn dedup_by_key() {
		let bounded_vec: BoundedVec<_, 2, 3> = BoundedVec::try_from(vec![1, 1, 2]).unwrap();
		let bounded_vec = bounded_vec.dedup_by_key(|x| *x).unwrap();
		assert_eq!(vec![1, 2], bounded_vec.to_vec());

		let bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::try_from(vec![1, 1, 2]).unwrap();
		assert_eq!(err(), bounded_vec.dedup_by_key(|x| *x));
	}

	#[test]
	fn dedup_by() {
		let bounded_vec: BoundedVec<_, 2, 3> = BoundedVec::try_from(vec![1, 1, 2]).unwrap();
		let bounded_vec = bounded_vec.dedup_by(|x, y| x == y).unwrap();
		assert_eq!(vec![1, 2], bounded_vec.to_vec());

		let bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::try_from(vec![1, 1, 2]).unwrap();
		assert_eq!(err(), bounded_vec.dedup_by(|x, y| x == y));
	}

	#[test]
	fn push() {
		let mut bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.push(4).unwrap();
		assert_eq!(vec![1, 2, 3, 4], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<_, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.push(4));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());
	}

	#[test]
	fn pop() {
		let mut bounded_vec: BoundedVec<_, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(3, bounded_vec.pop().unwrap());
		assert_eq!(vec![1, 2], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<_, 3, 5> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.pop());
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());
	}

	#[test]
	fn append() {
		let mut vec = vec![4, 5];
		let mut bounded_vec: BoundedVec<_, 3, 5> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.append(&mut vec).unwrap();
		assert_eq!(Vec::<i32>::new(), vec);
		assert_eq!(vec![1, 2, 3, 4, 5], bounded_vec.to_vec());

		let mut vec = vec![4, 5];
		let mut bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.append(&mut vec));
		assert_eq!(vec![4, 5], vec);
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec())
	}

	#[test]
	fn clear() {
		let mut bounded_vec: BoundedVec<_, 0, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.clear();
		assert_eq!(BoundedVec::new(), bounded_vec);
	}

	#[test]
	fn split_off() {
		let mut bounded_vec: BoundedVec<_, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(vec![3], bounded_vec.split_off(2).unwrap());
		assert_eq!(vec![1, 2], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.split_off(2));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec())
	}

	#[test]
	fn resize_with() {
		let mut bounded_vec: BoundedVec<_, 3, 5> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.resize_with(5, || 0).unwrap();
		assert_eq!(vec![1, 2, 3, 0, 0], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<_, 1, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.resize_with(1, || 0).unwrap();
		assert_eq!(vec![1], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.resize_with(5, || 0));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());

		let mut bounded_vec: BoundedVec<_, 2, 3> = BoundedVec::try_from(vec![1, 2, 3]).unwrap();
		assert_eq!(err(), bounded_vec.resize_with(1, || 0));
		assert_eq!(vec![1, 2, 3], bounded_vec.to_vec());
	}

	#[test]
	fn from_elem() {
		let bounded_vec: BoundedVec<_, 3, 4> = BoundedVec::from_elem(3, 4).unwrap();
		assert_eq!(vec![3, 3, 3, 3], bounded_vec.to_vec());

		let bounded_vec = BoundedVec::<_, 2, 3>::from_elem(3, 4);
		assert_eq!(err(), bounded_vec)
	}

	#[test]
	pub fn resize() {
		let mut bounded_vec = BoundedVec::<_, 1, 3>::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.resize(1, 2).unwrap();
		assert_eq!(&vec![1], bounded_vec.as_vec());
		bounded_vec.resize(3, 2).unwrap();
		assert_eq!(&vec![1, 2, 2], bounded_vec.as_vec());
		assert_eq!(err(), bounded_vec.resize(4, 2));
		assert_eq!(vec![1, 2, 2], bounded_vec.to_vec());
	}

	#[test]
	pub fn extend_from_slice() {
		let mut bounded_vec = BoundedVec::<_, 3, 5>::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.extend_from_slice(&[4, 5]).unwrap();
		assert_eq!(&vec![1, 2, 3, 4, 5], bounded_vec.as_vec());
		assert_eq!(err(), bounded_vec.extend_from_slice(&[6]));
		assert_eq!(&vec![1, 2, 3, 4, 5], bounded_vec.as_vec());
	}

	#[test]
	pub fn extend_from_within() {
		let mut bounded_vec = BoundedVec::<_, 3, 5>::try_from(vec![1, 2, 3]).unwrap();
		bounded_vec.extend_from_within(1..).unwrap();
		assert_eq!(&vec![1, 2, 3, 2, 3], bounded_vec.as_vec());
		bounded_vec.extend_from_within(4..4).unwrap();
		assert_eq!(&vec![1, 2, 3, 2, 3], bounded_vec.as_vec());
		assert_eq!(err(), bounded_vec.extend_from_within(4..=4));
		assert_eq!(&vec![1, 2, 3, 2, 3], bounded_vec.as_vec())
	}
}