univec 1.1.0

#![doc = include_str!("../README.md")]

use std::any::{Any, TypeId};
use std::fmt::{self, Debug, Formatter};
use std::mem;

pub use into_index::{At, AtMut, IntoIndex};

/// A dynamic vector that can store elements of any single type.
#[derive(Default)]
pub struct UniVec(Option<Box<dyn UniVecOps>>);

/// A macro to create a `UniVec` with elements.
/// This macro wraps the `vec!` macro creating an `UniVec` instead.
///
/// # Examples
///
/// ```
/// # use univec::univec;
/// let univec = univec![42, 10];
/// assert_eq!(univec.get::<i32>(0), Some(&42));
/// assert_eq!(univec.get::<i32>(1), Some(&10));
/// ```
#[macro_export]
macro_rules! univec {
    () => ( $crate::UniVec::new() );
    ($elem:expr; $n:expr) => ( $crate::UniVec::from(vec![$elem; $n]) );
    ($($x:expr),+ $(,)?) => { $crate::UniVec::from(vec![$($x),+]) };
}

impl UniVec {
    /// Creates a new empty `UniVec`. A new `UniVec` is empty and has no type associated to it,
    /// the type becomes associated when adding the first data to it.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let univec = UniVec::new();
    /// assert!(univec.is_empty());
    /// ```
    #[must_use]
    pub const fn new() -> Self {
        Self(None)
    }

    /// Creates a new empty `UniVec` with the specified capacity and type.
    ///
    /// # Arguments
    ///
    /// This function requires the 'turbofish' notation to associate a type to the `UniVec`.
    ///
    /// * `capacity` - The capacity to reserve.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let univec = UniVec::with_capacity::<i32>(10);
    /// assert!(univec.capacity() >= 10);
    /// ```
    #[must_use]
    pub fn with_capacity<T: 'static>(capacity: usize) -> Self {
        Self(Some(Box::new(Vec::<T>::with_capacity(capacity))))
    }

    /// Try to get a reference to an element of type `T` by index.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the element to retrieve.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(&T))` if the element is found, `Ok(None)` when the index is out of
    /// range. This includes indices that can't be converted to `usize`.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let element = univec.try_get::<i32>(0).unwrap();
    ///
    /// assert_eq!(element, Some(&42));
    /// ```
    pub fn try_get<T: 'static>(&self, index: impl IntoIndex) -> Result<Option<&T>, TypeError> {
        if let Ok(index) = index.try_into_index() {
            Ok(self.try_as_vec::<T>()?.and_then(|s| s.get(index)))
        } else {
            Ok(None)
        }
    }

    /// Get a reference to an element of type `T` by index. This resembles the the `Vec::get`
    /// method.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the element to retrieve.
    ///
    /// # Returns
    ///
    /// Returns `Some(&T)` it is found and `None` when the index is out of range.
    /// This includes indices that can't be converted to `usize`.
    ///
    /// # Panics
    ///
    /// Panics if this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let element = univec.get::<i32>(0).unwrap();
    ///
    /// assert_eq!(element, &42);
    /// ```
    #[must_use]
    pub fn get<T: 'static>(&self, index: impl IntoIndex) -> Option<&T> {
        self.as_vec::<T>().get(index.try_into_index().ok()?)
    }

    /// Try to get a mutable reference to an element of type `T` by index.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the element to retrieve.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(&mut T))` if the element is found, Ok(None) when the index is out of
    /// range. This includes indices that can't be converted to `usize`.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let mut element = univec.try_get_mut::<i32>(0).unwrap();
    ///
    /// if let Some(elem) = element {
    ///     *elem += 10;
    /// }
    ///
    /// assert_eq!(univec.try_get::<i32>(0).unwrap(), Some(&52));
    /// ```
    pub fn try_get_mut<T: 'static>(
        &mut self,
        index: impl IntoIndex,
    ) -> Result<Option<&mut T>, TypeError> {
        if let Ok(index) = index.try_into_index() {
            Ok(self.try_as_vec_mut::<T>()?.and_then(|s| s.get_mut(index)))
        } else {
            Ok(None)
        }
    }

    /// Get a mutable reference to an element of type `T` by index. Will associate `Self` with
    /// a empty `Vec<T>` when the `UniVec` is not associated to a type.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the element to retrieve.
    ///
    /// # Returns
    ///
    /// Returns `Some(&mut T)` it is found and `None` when the index is out of range.
    /// This includes indices that can't be converted to `usize`.
    ///
    /// # Panics
    ///
    /// Panics if this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let mut element = univec.get_mut::<i32>(0).unwrap();
    ///
    /// *element += 10;
    ///
    /// assert_eq!(univec.get::<i32>(0), Some(&52));
    /// ```
    #[must_use]
    pub fn get_mut<T: 'static>(&mut self, index: impl IntoIndex) -> Option<&mut T> {
        self.as_vec_mut::<T>().get_mut(index.try_into_index().ok()?)
    }

    /// Ensures that the `UniVec` stores `T's`. Possibly associate the requested type and
    /// reserving the specified capacity.
    ///
    /// # Arguments
    ///
    /// * `capacity` - The capacity to reserve.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the `UniVec` was empty or `T` was already is associated.
    /// The requested capacity is reserved then.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.ensure::<i32>(10).unwrap();
    /// assert!(univec.capacity() >= 10);
    /// assert_eq!(univec.associated_type(), Some(std::any::TypeId::of::<i32>()));
    /// ```
    pub fn ensure<T: 'static>(&mut self, capacity: usize) -> Result<(), TypeError> {
        if self.0.is_none() {
            self.0 = Some(Box::new(Vec::<T>::with_capacity(capacity)));
        } else if !self.type_check::<T>() {
            return Err(TypeError);
        }

        self.reserve(capacity);
        Ok(())
    }

    /// Pushes a value of type `T` onto a `UniVec`.
    ///
    /// # Arguments
    ///
    /// * `value` - A `T` to push onto self.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the value was successfully pushed.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeErrorValue(value))` when this `UniVec` can not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let mut element = univec.get_mut::<i32>(0);
    ///
    /// if let Some(elem) = element {
    ///     *elem += 10;
    /// }
    ///
    /// assert_eq!(univec.get::<i32>(0), Some(&52));
    /// ```
    pub fn push<T: 'static>(&mut self, value: T) -> Result<(), TypeErrorValue<T>> {
        if self.ensure::<T>(1).is_ok() {
            self.as_vec_mut::<T>().push(value);
            Ok(())
        } else {
            Err(TypeErrorValue(value))
        }
    }

    /// Pops a dynamic typed value from a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Some(Box<dyn Any>)` if a value is successfully popped. `None` when the univec
    /// was empty.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let popped = univec.pop_any().unwrap();
    ///
    /// assert_eq!(*popped.downcast::<i32>().unwrap(), 42);
    /// ```
    #[must_use]
    pub fn pop_any(&mut self) -> Option<Box<dyn Any>> {
        self.0.as_mut().and_then(|vec| vec.pop_box())
    }

    /// Pops a value of type `T` from a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(T))` with the value is successfully popped.
    /// Returns `Ok(None)` when the univec is empty.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when the univec does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let popped = univec.pop().unwrap();
    ///
    /// assert_eq!(popped, Some(42));
    /// assert!(univec.is_empty());
    /// ```
    #[allow(clippy::missing_panics_doc)]
    pub fn pop<T: 'static>(&mut self) -> Result<Option<T>, TypeError> {
        Ok(self.try_as_vec_mut::<T>()?.and_then(Vec::pop))
    }

    /// Drops the last value from a `UniVec`. This is more efficient than the other `pop`
    /// variants when the value is not required anymore.
    ///
    /// # Returns
    ///
    /// Returns `true` if a value is successfully dropped, otherwise returns `false`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// assert!(univec.drop_last());
    /// assert!(univec.is_empty());
    /// ```
    pub fn drop_last(&mut self) -> bool {
        self.0.as_mut().map_or(false, |vec| vec.drop_last())
    }

    /// Inserts a value of type `T` into the `UniVec` at the specified index.
    ///
    /// # Arguments
    ///
    /// * `index` - The index at which to insert the value.
    /// * `value` - A reference to the value of type `T` to insert into the vector.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeErrorValue(value))` when this `UniVec` does not store `T's`.
    ///
    /// # Panics
    ///
    /// Panics if the index is out of bounds.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// univec.insert(0, 10_i32).unwrap();
    ///
    /// assert_eq!(univec.get::<i32>(0), Some(&10));
    /// assert_eq!(univec.get::<i32>(1), Some(&42));
    /// ```
    pub fn insert<T: 'static>(
        &mut self,
        index: impl IntoIndex,
        value: T,
    ) -> Result<(), TypeErrorValue<T>> {
        if self.ensure::<T>(1).is_ok() {
            // PLANNED: v2.0 report error instead panic
            self.as_vec_mut::<T>().insert(index.into_index(), value);
            Ok(())
        } else {
            Err(TypeErrorValue(value))
        }
    }

    /// Removes a value of type `T` from an `UniVec` at the specified index.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the element to remove.
    ///
    /// # Panics
    ///
    /// Panics if index is out of bounds.
    ///
    /// # Returns
    ///
    /// Returns `Ok(T)` if a value is successfully removed.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let removed = univec.remove::<i32>(0).unwrap();
    ///
    /// assert_eq!(removed, 42);
    /// ```
    pub fn remove<T: 'static>(&mut self, index: impl IntoIndex) -> Result<T, TypeError> {
        Ok(self
            .try_as_vec_mut::<T>()?
            // PLANNED: v2.0 report error instead panic
            .map(|v| v.remove(index.into_index()))
            .expect("index out of bounds"))
    }

    /// Returns the length of a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns the length of the `UniVec`. A `UniVec` with no type associated is considered
    /// empty with length 0.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// assert_eq!(univec.len(), 0);
    ///
    /// univec.push(42_i32);
    ///
    /// assert_eq!(univec.len(), 1);
    /// ```
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.as_ref().map_or(0, |vec| vec.len())
    }

    /// Returns whether a `UniVec` is empty.
    ///
    /// # Returns
    ///
    /// Returns `true` when the `UniVec` is empty, otherwise returns `false`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let univec = UniVec::new();
    ///
    /// assert!(univec.is_empty());
    /// ```
    #[must_use]
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.0.as_ref().map_or(true, |vec| vec.len() == 0)
    }

    /// Returns the capacity of a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns the capacity of the `UniVec`. A `UniVec` with no type associated is considered
    /// empty with capacity 0.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// assert_eq!(univec.capacity(), 0);
    ///
    /// univec.push(42_i32);
    ///
    /// assert!(univec.capacity() >= 1);
    /// ```
    #[must_use]
    pub fn capacity(&self) -> usize {
        self.0.as_ref().map_or(0, |vec| vec.capacity())
    }

    /// Reserves capacity for at least additional more elements to be inserted in the given
    /// `UniVec`. The collection may reserve more space to avoid frequent reallocations. Note
    /// that `reserve()` will not reserve elements on a `UniVec` that has no type associated,
    /// use `UniVec::with_capacity()` to initialize a `Univec` or `UniVec::ensure()` to
    /// associate a type while reserving some elements.
    ///
    /// # Arguments
    ///
    /// * `additional` - The number of additional elements to reserve space for.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// univec.reserve(10);
    /// assert!(univec.capacity() >= 11);
    /// ```
    pub fn reserve(&mut self, additional: usize) {
        if let Some(v) = self.0.as_mut() {
            v.reserve(additional);
        };
    }

    /// Replaces the element at the specified index with a new value.
    ///
    /// # Arguments
    ///
    /// * `index` - The index of the element to replace.
    /// * `value` - The new value to replace the element with.
    ///
    /// # Panics
    ///
    /// Panics if index is out of bounds.
    ///
    /// # Returns
    ///
    /// Returns `Ok(T)` with the old value if a value is successfully replaced.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeErrorValue(value))` when this `UniVec` does not store `T's`.
    ///
    /// # Panics
    ///
    /// Panics if index is out of bounds.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    /// univec.push(42_i32);
    ///
    /// let removed = univec.replace(0, 10_i32).unwrap();
    ///
    /// assert_eq!(removed, 42);
    /// assert_eq!(univec.get::<i32>(0), Some(&10));
    /// ```
    pub fn replace<T: 'static>(
        &mut self,
        index: impl IntoIndex,
        value: T,
    ) -> Result<T, TypeErrorValue<T>> {
        if self.type_check::<T>() {
            Ok(mem::replace(
                // PLANNED: v2.0 report error instead panic
                self.get_mut::<T>(index.into_index())
                    .expect("index out of bounds"),
                value,
            ))
        } else {
            Err(TypeErrorValue(value))
        }
    }

    /// Tries to sets the last element of an `UniVec` to a new value. When the `UniVec` is
    /// empty or not associated to a type, an initial value is pushed.
    ///
    /// # Arguments
    ///
    /// * `value` - the new value to replace the last element with.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(T))` with the old last element or `Ok(None)` when the univec was
    /// empty.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeErrorValue(value))` when this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.try_set_last(10_i32).unwrap();
    /// assert_eq!(univec.get::<i32>(0), Some(&10));
    ///
    /// univec.try_set_last(20_i32).unwrap();
    /// assert_eq!(univec.get::<i32>(0), Some(&20));
    /// ```
    pub fn try_set_last<T: 'static>(&mut self, value: T) -> Result<Option<T>, TypeErrorValue<T>> {
        Ok(if self.is_empty() {
            self.push(value)?;
            None
        } else {
            Some(self.replace(self.len() - 1, value)?)
        })
    }

    /// Sets the last element of an `UniVec` to a new value. When the `UniVec` is
    /// empty or not associated to a type, an initial value is pushed.
    ///
    /// # Arguments
    ///
    /// * `value` - The new value to replace the last element with.
    ///
    /// # Returns
    ///
    /// Returns `Some(T)` with the old last element or `None` when the univec was empty.
    ///
    /// # Panics
    ///
    /// Panics if this `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.set_last(10_i32);
    /// assert_eq!(univec.get::<i32>(0), Some(&10));
    ///
    /// univec.set_last(20_i32);
    /// assert_eq!(univec.get::<i32>(0), Some(&20));
    /// ```
    pub fn set_last<T: 'static>(&mut self, value: T) -> Option<T> {
        self.try_set_last(value)
            .unwrap_or_else(|_| panic!("This UniVec does not store the requested type"))
    }

    /// Checks whenever this `UniVec` is capable of storing `T`.
    #[inline]
    fn type_check<T: 'static>(&self) -> bool {
        self.0
            .as_ref()
            .map_or(true, |vec| vec.inner_type_id() == TypeId::of::<T>())
    }

    /// Returns an `Option<TypeId>` the type is associated to a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Some(TypeId)` if a type is associated to this `UniVec`, otherwise returns `None`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// assert_eq!(univec.associated_type(), None);
    ///
    /// univec.push(42_i32);
    ///
    /// assert_eq!(univec.associated_type(), Some(std::any::TypeId::of::<i32>()));
    /// ```
    #[must_use]
    pub fn associated_type(&self) -> Option<TypeId> {
        self.0.as_ref().map(|vec| vec.inner_type_id())
    }

    /// Returns the name of the type is associated to a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Some('static str)` if a type is associated to this `UniVec`, otherwise returns `None`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// assert_eq!(univec.associated_type_name(), None);
    ///
    /// univec.push(42_i32);
    ///
    /// assert_eq!(univec.associated_type_name(), Some("i32"));
    /// ```
    #[must_use]
    pub fn associated_type_name(&self) -> Option<&'static str> {
        self.0.as_ref().map(|vec| vec.inner_type_name())
    }

    /// Takes the underlying original `Vec<T>` out of the `UniVec` and returns it.
    /// `self` is left non associated and can be used to store a different type.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(Vec<T>))` when the underlying vector is successfully taken.
    /// Returns `Ok(None)` when `self` had no type associated.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when the `UniVec` does not store `T's`.
    /// The `UniVec` is left unchanged then.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let vec = univec.take::<i32>().unwrap().unwrap();
    ///
    /// assert_eq!(vec, vec![42]);
    /// ```
    pub fn take<T: 'static>(&mut self) -> Result<Option<Vec<T>>, TypeError> {
        if self.is_empty() {
            Ok(None)
        } else if self.type_check::<T>() {
            // SAFETY: We just checked the type_id and that the UniVec is not empty
            unsafe {
                let vec = self.0.take().unwrap_unchecked();
                // PLANNED: use Box::into_inner() once stable or trait downcasting when available.
                #[allow(clippy::cast_ptr_alignment)]
                Ok(Some(*Box::from_raw(Box::into_raw(vec).cast::<Vec<T>>())))
            }
        } else {
            Err(TypeError)
        }
    }

    /// Returns the underlying original `Vec<T>` of a `UniVec`. Consumes the `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(Vec<T>))` if the underlying vector was successfully taken.
    /// Returns `Ok(None)` when the `UniVec` was empty.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeErrorIntoInner(self))` when the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let vec = univec.into_inner::<i32>().unwrap().unwrap();
    ///
    /// assert_eq!(vec, vec![42]);
    /// ```
    pub fn into_inner<T: 'static>(mut self) -> Result<Option<Vec<T>>, TypeErrorIntoInner> {
        if self.is_empty() {
            Ok(None)
        } else if self.type_check::<T>() {
            // SAFETY: We just checked the type_id and that the UniVec is not empty
            unsafe {
                let vec = self.0.take().unwrap_unchecked();
                // PLANNED: use Box::into_inner() once stable or trait downcasting when available.
                #[allow(clippy::cast_ptr_alignment)]
                Ok(Some(*Box::from_raw(Box::into_raw(vec).cast::<Vec<T>>())))
            }
        } else {
            Err(TypeErrorIntoInner(self))
        }
    }

    /// Try to get a reference to the underlying original `Vec<T>` of a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(&Vec<T>))` when the underlying `Vec<T>` is available.
    /// Returns `Ok(None)` when the `UniVec` is not associated with any type.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let vec = univec.try_as_vec::<i32>().unwrap().unwrap();
    ///
    /// assert_eq!(*vec, vec![42]);
    /// ```
    pub fn try_as_vec<T: 'static>(&self) -> Result<Option<&Vec<T>>, TypeError> {
        self.0
            .as_ref()
            .map(|b| b.as_any().downcast_ref::<Vec<T>>().ok_or(TypeError))
            .transpose()
    }

    /// Get a reference to the underlying original `Vec<T>` of a `UniVec`.
    ///
    /// # Panics
    ///
    /// Panics if the `UniVec` does not store `T's` this includes the case when it has no
    /// associated type.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let vec = univec.as_vec::<i32>();
    ///
    /// assert_eq!(*vec, vec![42]);
    /// ```
    #[must_use]
    pub fn as_vec<T: 'static>(&self) -> &Vec<T> {
        self.0
            .as_ref()
            .expect("This Univec has no type associated")
            .as_any()
            .downcast_ref::<Vec<T>>()
            .expect("This UniVec does not store the requested type")
    }

    // PLANNED: when stable
    // unsafe fn as_vec_unchecked<T: 'static>(&mut self) -> &mut Vec<T> {
    //      self.0
    //         .as_ref()
    //         .unwrap_unchecked()
    //         .as_any()
    //         .downcast_unchecked::<Vec<T>>()
    // }

    /// Try to get a mutable reference to the underlying original `Vec<T>` of a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(&mut Vec<T>))` if the underlying `Vec<T>` is available.
    /// Returns `Ok(None)` when the `UniVec` is not associated to a type.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let vec = univec.try_as_vec_mut::<i32>().unwrap().unwrap();
    ///
    /// vec.push(10);
    ///
    /// assert_eq!(*vec, vec![42, 10]);
    /// ```
    pub fn try_as_vec_mut<T: 'static>(&mut self) -> Result<Option<&mut Vec<T>>, TypeError> {
        self.0
            .as_mut()
            .map(|b| b.as_any_mut().downcast_mut::<Vec<T>>().ok_or(TypeError))
            .transpose()
    }

    /// Get a mutable reference to the underlying original `Vec<T>` of a `UniVec`. Will
    /// associate `Self` with a empty `Vec<T>` when the `UniVec` is not associated to a type.
    ///
    /// # Panics
    ///
    /// Panics if the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let vec = univec.as_vec_mut::<i32>();
    ///
    /// vec.push(10);
    ///
    /// assert_eq!(*vec, vec![42, 10]);
    /// ```
    #[must_use]
    pub fn as_vec_mut<T: 'static>(&mut self) -> &mut Vec<T> {
        let _ = self.ensure::<T>(0);
        self.0
            .as_mut()
            .expect("This Univec has no type associated")
            .as_any_mut()
            .downcast_mut::<Vec<T>>()
            .expect("This UniVec does not store the requested type")
    }

    // PLANNED: when stable
    // unsafe fn vec_mut_unchecked<T: 'static>(&mut self) -> &mut Vec<T> {
    //      self.0
    //         .as_mut()
    //         .unwrap_unchecked()
    //         .as_any_mut()
    //         .downcast_mut_unchecked::<Vec<T>>()
    // }

    /// Try to get a reference to a slice of underlying original `Vec<T>` of a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(&[T]))` if the underlying `Vec<T>` is available.
    /// Returns `Ok(None)` when the `UniVec` is not associated to a type.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let slice = univec.try_as_slice::<i32>().unwrap().unwrap();
    ///
    /// assert_eq!(slice, &[42]);
    /// ```
    #[inline]
    pub fn try_as_slice<T: 'static>(&self) -> Result<Option<&[T]>, TypeError> {
        Ok(self.try_as_vec::<T>()?.map(Vec::as_slice))
    }

    /// Get a reference to a slice of underlying original `Vec<T>` of a `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `&[T]` if the underlying `Vec<T>` is available.
    ///
    /// # Panics
    ///
    /// Panics if the `UniVec` does not store `T's` or has no associated type.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let slice = univec.as_slice::<i32>();
    ///
    /// assert_eq!(slice, &[42]);
    /// ```
    #[inline]
    #[must_use]
    pub fn as_slice<T: 'static>(&self) -> &[T] {
        self.as_vec::<T>().as_slice()
    }

    /// Try to get a mutable reference to a slice of underlying original `Vec<T>` of a
    /// `UniVec`.
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(&mut [T]))` if the underlying `Vec<T>` is available.
    /// Returns `Ok(None)` when the `UniVec` is not associated to a type.
    ///
    /// # Errors
    ///
    /// Returns `Err(TypeError)` when the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let slice = univec.try_as_mut_slice::<i32>().unwrap().unwrap();
    ///
    /// slice[0] = 10;
    ///
    /// assert_eq!(slice, &[10]);
    /// assert_eq!(univec.get::<i32>(0), Some(&10));
    /// ```
    #[inline]
    pub fn try_as_mut_slice<T: 'static>(&mut self) -> Result<Option<&mut [T]>, TypeError> {
        Ok(self.try_as_vec_mut::<T>()?.map(Vec::as_mut_slice))
    }

    /// Get a mutable reference to a slice of underlying original `Vec<T>` of a `UniVec`.
    /// Will associate `Self` with a empty `Vec<T>` when the `UniVec` is not associated to a
    /// type.
    ///
    /// # Returns
    ///
    /// Returns the underlying `&mut [T]`.
    ///
    /// # Panics
    ///
    /// Panics if the `UniVec` does not store `T's`.
    ///
    /// # Example
    ///
    /// ```
    /// # use univec::UniVec;
    /// let mut univec = UniVec::new();
    ///
    /// univec.push(42_i32);
    ///
    /// let slice = univec.as_mut_slice::<i32>();
    ///
    /// slice[0] = 10;
    ///
    /// assert_eq!(slice, &[10]);
    /// assert_eq!(univec.get::<i32>(0), Some(&10));
    /// ```
    #[inline]
    #[must_use]
    pub fn as_mut_slice<T: 'static>(&mut self) -> &mut [T] {
        self.as_vec_mut::<T>().as_mut_slice()
    }
}

// UniVec needs a custom Debug implementation to relax the requirement of T: Debug.
impl Debug for UniVec {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        match self.0 {
            Some(ref vec) => write!(f, "UniVec(Some(Vec<{}>))", vec.inner_type_name()),
            None => write!(f, "UniVec(None)"),
        }
    }
}

// private trait
trait UniVecOps: Any {
    /// Pops a value from the `UniVec` as a boxed trait object.
    ///
    /// # Returns
    ///
    /// Returns `Some(Box<dyn Any>)` if a value is successfully popped, otherwise returns `None`.
    fn pop_box(&mut self) -> Option<Box<dyn Any>>;

    /// Pops and drops a value from the univec.
    ///
    /// # Returns
    ///
    /// Returns `true` if a value is successfully popped, otherwise returns `false`.
    fn drop_last(&mut self) -> bool;

    /// Returns the length of an `UniVec`.
    fn len(&self) -> usize;

    /// Returns the capacity of an `UniVec`.
    fn capacity(&self) -> usize;

    /// Reserve capacity for at least additional more elements to be inserted in the given.
    fn reserve(&mut self, additional: usize);

    /// Returns the `TypeId` of the stored elements
    fn inner_type_id(&self) -> TypeId;

    /// Returns the type name of the stored elements
    fn inner_type_name(&self) -> &'static str;

    /// Coerces `&self` to `&dyn Any`.
    fn as_any(&self) -> &dyn Any;

    /// Coerces `&mut self` to `&mut dyn Any`.
    fn as_any_mut(&mut self) -> &mut dyn Any;
}

impl<T> UniVecOps for Vec<T>
where
    T: 'static,
{
    fn pop_box(&mut self) -> Option<Box<dyn Any>> {
        let value = self.pop()?;
        Some(Box::new(value))
    }

    #[inline]
    fn drop_last(&mut self) -> bool {
        self.pop().is_some()
    }

    #[inline]
    fn len(&self) -> usize {
        self.len()
    }

    #[inline]
    fn capacity(&self) -> usize {
        self.capacity()
    }

    #[inline]
    fn reserve(&mut self, additional: usize) {
        self.reserve(additional);
    }

    #[inline]
    fn inner_type_id(&self) -> TypeId {
        TypeId::of::<T>()
    }

    fn inner_type_name(&self) -> &'static str {
        std::any::type_name::<T>()
    }

    #[inline]
    fn as_any(&self) -> &dyn Any {
        self
    }

    #[inline]
    fn as_any_mut(&mut self) -> &mut dyn Any {
        self
    }
}

impl<T> From<Vec<T>> for UniVec
where
    T: 'static,
{
    #[inline]
    fn from(vec: Vec<T>) -> Self {
        Self(Some(Box::new(vec)))
    }
}

impl<T> AsRef<[T]> for UniVec
where
    T: 'static,
{
    #[inline]
    fn as_ref(&self) -> &[T] {
        self.as_slice()
    }
}

impl<T> AsMut<[T]> for UniVec
where
    T: 'static,
{
    #[inline]
    fn as_mut(&mut self) -> &mut [T] {
        self.as_mut_slice()
    }
}

/// Error that happens on a query when the requested type is not stored in the `UniVec`.
// PLANNED: v2.0 enum {TypeError, RangeError}
#[derive(thiserror::Error, Debug, PartialEq)]
#[error("This UniVec does not store the requested type")]
pub struct TypeError;

/// When pushing/setting an element fails because of a type error, one gets the failed element back.
// PLANNED: v2.0 enum {TypeErrorValue<T>, RangeErrorValue<T>}
#[derive(thiserror::Error, PartialEq)]
#[error("This UniVec does not store the requested type")]
pub struct TypeErrorValue<T>(
    /// The element that failed to insert.
    pub T,
);

// needs a custom debug implementation to relax the requirement of T: Debug.
impl<T> Debug for TypeErrorValue<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "TypeErrorValue<{}>", std::any::type_name::<T>())
    }
}

/// When `UniVec::into_inner()` fails because of a type error, one gets the failed `UniVec` back.
#[derive(thiserror::Error, Debug)]
#[error("This UniVec does not store the requested type")]
pub struct TypeErrorIntoInner(
    /// The `UniVec` that failed to convert into the inner `Vec<T>`.
    pub UniVec,
);

#[cfg(test)]
mod tests {
    use super::*;

    // test UniVec::type_check()
    #[test]
    fn test_type_check() {
        let mut univec = UniVec::new();
        assert!(univec.type_check::<i64>());
        univec.push(42_i32).unwrap();
        assert!(univec.type_check::<i32>());
        assert!(!univec.type_check::<i64>());
    }
}