ot-tools-io 0.8.0

/*
SPDX-License-Identifier: GPL-3.0-or-later
Copyright © 2024 Mike Robeson [dijksterhuis]
*/

//! standard library methods for generic new types (methods delegate to the inner type).

macro_rules! methods_base {
    ($inner_t:ident, $n:expr) => {
        /// Returns the number of elements in the slice.
        pub fn len(&self) -> usize {
            self.0.len()
        }

        /// Returns `true` if the slice has a length of 0
        pub fn is_empty(&self) -> bool {
            self.0.is_empty()
        }

        /// Returns the index that an element reference points to.
        pub fn element_offset(&self, element: &$inner_t) -> Option<usize> {
            self.0.element_offset(element)
        }

        /// Returns an iterator over the slice.
        ///
        /// The iterator yields all items from start to end.
        pub fn iter(&self) -> Iter<'_, $inner_t> {
            self.0.iter()
        }

        /// Returns an iterator that allows modifying each value.
        ///
        /// The iterator yields all items from start to end.
        pub fn iter_mut(&mut self) -> IterMut<'_, $inner_t> {
            self.0.iter_mut()
        }

        /// Fills `self` with elements returned by calling a closure repeatedly.
        ///
        /// This method uses a closure to create new values. If you'd rather `Clone` a given value, use
        /// `fill`.
        ///
        /// If you want to use the `Default` trait to generate values, you can pass `Default::default`
        /// as the argument
        pub fn fill_with<F: FnMut() -> $inner_t>(&mut self, f: F) -> () {
            self.0.fill_with(f)
        }

        /// Returns a reference to the first item in the slice, or `None` if it is empty
        pub fn first(&self) -> Option<&$inner_t> {
            self.0.first()
        }

        /// Returns a mutable reference to the first item in the slice, or `None` if it is empty
        pub fn first_mut(&mut self) -> Option<&mut $inner_t> {
            self.0.first_mut()
        }

        /// Returns a reference to the last item in the slice, or `None` if it is empty
        pub fn last(&self) -> Option<&$inner_t> {
            self.0.last()
        }

        /// Returns a mutable reference to the last item in the slice, or `None` if it is empty
        pub fn last_mut(&mut self) -> Option<&mut $inner_t> {
            self.0.last_mut()
        }

        /// returns a referenced array of the underlying data
        pub fn as_slice(&self) -> &[$inner_t] {
            self.0.as_slice()
        }

        /// returns a mutable reference array of the underlying data
        pub fn as_mut_slice(&mut self) -> &mut [$inner_t] {
            self.0.as_mut_slice()
        }

        /// returns a referenced array of the underlying data
        pub fn as_array<const N: usize>(&self) -> Option<&[$inner_t; N]> {
            self.0.as_array()
        }

        /// returns a referenced array of the underlying data
        pub fn as_mut_array<const N: usize>(&mut self) -> Option<&mut [$inner_t; N]> {
            self.0.as_mut_array()
        }

        /// Borrows each element and returns an array of references with the same size as `self`.
        ///
        /// see `core::array::each_ref`
        pub fn each_ref(&self) -> [&$inner_t; $n] {
            self.0.each_ref()
        }

        /// Borrows each element mutably and returns an array of mutable references with the same size
        /// as `self`.
        ///
        /// see `core::array::each_mut`
        pub fn each_mut(&mut self) -> [&mut $inner_t; $n] {
            self.0.each_mut()
        }

        /// Returns a reference to an element or subslice depending on the type of
        /// index.
        pub fn get(&self, index: usize) -> Option<&$inner_t> {
            self.0.get(index)
        }

        /// Returns a mutable reference to an element or subslice depending on the type of
        /// index.
        pub fn get_mut(&mut self, index: usize) -> Option<&mut $inner_t> {
            self.0.get_mut(index)
        }

        /// Splits the slice into a slice of `N`-element arrays, starting at the beginning of the slice,
        /// and a remainder slice with length strictly less than `N`.
        ///
        /// see `core::slice::as_chunks`
        pub fn as_chunks<const N: usize>(&self) -> (&[[$inner_t; N]], &[$inner_t]) {
            self.0.as_chunks()
        }

        /// Splits the slice into a slice of `N`-element arrays, starting at the beginning of the slice,
        /// and a remainder slice with length strictly less than `N`.
        ///
        /// see `core::slice::as_chunks_mut`
        pub fn as_chunks_mut<const N: usize>(&mut self) -> (&mut [[$inner_t; N]], &mut [$inner_t]) {
            self.0.as_chunks_mut()
        }

        /// Returns an iterator over subslices separated by elements that match `pred`.
        /// The matched element is not contained in the subslices
        pub fn split<F: FnMut(&$inner_t) -> bool>(&self, pred: F) -> Split<'_, $inner_t, F> {
            self.0.split(pred)
        }

        /// Returns an iterator over mutable subslices separated by elements that match `pred`.
        /// The matched element is not contained in the subslices
        pub fn split_mut<F: FnMut(&$inner_t) -> bool>(
            &mut self,
            pred: F,
        ) -> SplitMut<'_, $inner_t, F> {
            self.0.split_mut(pred)
        }

        /// Divides one slice into two at an index.
        pub fn split_at(&self, mid: usize) -> (&[$inner_t], &[$inner_t]) {
            self.0.split_at(mid)
        }

        /// Divides one mutable slice into two at an index.
        pub fn split_at_mut(&mut self, mid: usize) -> (&mut [$inner_t], &mut [$inner_t]) {
            self.0.split_at_mut(mid)
        }

        /// Divides one slice into two at an index, returning `None` if the slice is too short.
        pub fn split_at_checked(&self, mid: usize) -> Option<(&[$inner_t], &[$inner_t])> {
            self.0.split_at_checked(mid)
        }

        /// Divides one mutable slice into two at an index, returning `None` if the slice is too short.
        pub fn split_at_mut_checked(
            &mut self,
            mid: usize,
        ) -> Option<(&mut [$inner_t], &mut [$inner_t])> {
            self.0.split_at_mut_checked(mid)
        }

        /// Returns the first and all the rest of the elements of the slice, or `None` if it is empty.
        pub fn split_first(&self) -> Option<(&$inner_t, &[$inner_t])> {
            self.0.split_first()
        }

        /// Returns the first and all the rest of the elements of the slice as mutable, or `None` if it is empty.
        pub fn split_first_mut(&mut self) -> Option<(&mut $inner_t, &mut [$inner_t])> {
            self.0.split_first_mut()
        }

        /// Returns the last and all the rest of the elements of the slice, or `None` if it is empty.
        pub fn split_last(&self) -> Option<(&$inner_t, &[$inner_t])> {
            self.0.split_last()
        }

        /// Returns the last and all the rest of the elements of the slice as mutable, or `None` if it is empty.
        pub fn split_last_mut(&mut self) -> Option<(&mut $inner_t, &mut [$inner_t])> {
            self.0.split_last_mut()
        }

        /// Returns an iterator over subslices separated by elements that match `pred`.
        /// The matched element is contained in the end of the previous subslice as a terminator.
        pub fn split_inclusive<F: FnMut(&$inner_t) -> bool>(
            &self,
            f: F,
        ) -> SplitInclusive<'_, $inner_t, F> {
            self.0.split_inclusive(f)
        }

        /// Returns an iterator over mutable subslices separated by elements that match `pred`.
        /// The matched element is contained in the end of the previous subslice as a terminator.
        pub fn split_inclusive_mut<F: FnMut(&$inner_t) -> bool>(
            &mut self,
            f: F,
        ) -> SplitInclusiveMut<'_, $inner_t, F> {
            self.0.split_inclusive_mut(f)
        }
    };
}
macro_rules! methods_partial_eq {
    ($inner_t:ident) => {
        /// Returns true if the slice contains an element with the given value.
        /// This operation is O(n).
        pub fn contains(&self, x: &$inner_t) -> bool {
            self.0.contains(x)
        }
    };
}

macro_rules! methods_copy {
    ($inner_t:ident, $n:expr) => {
        // /// Creates a consuming iterator, that is, one that moves each value out of the array (from
        // /// start to end).
        // ///
        // /// The array cannot be used after calling this unless `T` implements `Copy`, so the whole array
        // /// is copied.
        // pub fn into_iter(self) -> IntoIter<$inner_t, $n> {
        //     self.0.into_iter()
        // }

        /// Returns an array of the same size as `self`, with function `f` applied to each element in order.
        pub fn map<F: FnMut($inner_t) -> U, U>(self, f: F) -> [U; $n] {
            self.0.map(f)
        }

        /// Creates a vector by copying a slice `n` times.
        ///
        /// see `alloc::slice::repeat`
        ///
        /// Useful for duplicating heterogeneous track data when ownership is required for both the
        /// source data and the duplicates
        pub fn repeat(&mut self, n: usize) -> Vec<$inner_t> {
            self.0.repeat(n)
        }

        /// Copies the elements from `src` into `self`, using a memcpy.
        ///
        /// The length of `src` must be the same as `self`.
        pub fn copy_from_slice(&mut self, src: &[$inner_t]) -> () {
            self.0.copy_from_slice(src)
        }
    };
}

macro_rules! methods_clone {
    ($inner_t:ident, $n:expr) => {
        /// Fills `self` with elements by cloning `value`.
        pub fn fill(&mut self, value: $inner_t) -> () {
            self.0.fill(value)
        }

        /// Copies `self` into a new `Vec` using `Clone`
        pub fn to_vec(&self) -> Vec<$inner_t> {
            self.0.to_vec()
        }

        /// Copies the elements from `src` into `self`.
        ///
        /// The length of `src` must be the same as `self`.
        pub fn clone_from_slice(&mut self, src: &[$inner_t]) -> () {
            self.0.clone_from_slice(src)
        }

        /// Uses borrowed data to replace owned data, usually by cloning.
        // todo: generic argument with asref and asmut
        pub fn clone_into(&mut self, target: &mut Self) -> () {
            self.0.clone_into(&mut target.0)
        }
    };
}

// requires Copy!
macro_rules! method_id {
    ($inner_t:ident, $id:ident) => {
        /// Returns an owned element of the array data
        ///
        /// # Panic-free
        ///
        /// This method is panic-free as the `id` type is guaranteed to never exceed the max index
        /// of the underlying array.
        pub fn id(self, id: &$id) -> $inner_t {
            self.0[id.as_index()]
        }
    };
}

macro_rules! method_id_ref {
    ($inner_t:ident, $id:ident) => {
        /// Returns a reference to an element of the array data
        ///
        /// # Panic-free
        ///
        /// This method is panic-free as the `id` type is guaranteed to never exceed the max index
        /// of the underlying array.
        pub fn id_ref(&self, id: &$id) -> &$inner_t {
            &self.0[id.as_index()]
        }
    };
}

macro_rules! method_id_mut {
    ($inner_t:ident, $id:ident) => {
        /// Returns a mutable reference to an element the array data
        ///
        /// # Panic-free
        ///
        /// This method is panic-free as the `id` type is guaranteed to never exceed the max index
        /// of the underlying array.
        pub fn id_mut(&mut self, id: &$id) -> &mut $inner_t {
            &mut self.0[id.as_index()]
        }
    };
}

/// Adds most standard methods for arrays to a newtype which holds array data
///
/// # Standard/Delegated Method Implementations
///
/// Only methods which *do not alter the size of the underlying array* are implemented.
///
/// Modifying the size of the underlying array via delgaated/passed-through methods doesn't make
/// sense because data stored in a newtype should always have N elements. So methods like `concat()`
/// have not been implemented on purpose.
///
/// Also, altering the order of array elements sometimes doesn't make sense. Care needs to be taken
/// when modifying and data types that hold a `track_id` field -- such as [`AudioTrackTrigs`] and
/// [`MidiTrackTrigs`]. As a result, methods which change data order, such as `reverse()` or
/// `copy_within()`, have not been implemented either.
///
/// [`AudioTrackTrigs`]: [crate::patterns::AudioTrackTrigs]
/// [`MidiTrackTrigs`]: [crate::patterns::MidiTrackTrigs]
macro_rules! generic_newtype_method_delegate {
    ($name:ident, $n:expr) => {
        impl<T> $name<T> {
            methods_base!(T, $n);
        }

        impl<T: PartialEq> $name<T> {
            methods_partial_eq!(T);
        }

        impl<T: Copy> $name<T> {
            methods_copy!(T, $n);
        }

        impl<T: Clone> $name<T> {
            methods_clone!(T, $n);
        }
    };
}

/// Adds "unbox-ing" methods to a newtype that holds boxed array data
macro_rules! generic_newtype_unbox {
    ($name:ident, $n:expr) => {
        impl<T> $name<T> {
            /// Returns an owned `[T; 16]` by "un-boxing" (dereferencing) the data
            pub fn unbox(self) -> [T; $n] {
                *self.0
            }

            /// Returns a referenced `[T; 16]` by "un-boxing" (dereferencing) the data
            pub fn unbox_ref(&self) -> &[T; $n] {
                &*self.0
            }

            /// Returns a mutably referenced `[T; 16]` by "un-boxing" (dereferencing) the data
            pub fn unbox_mut(&mut self) -> &mut [T; $n] {
                &mut *self.0
            }
        }
    };
}

/// Adds ID based lookup methods to a newtype that holds array data that can be looked up with the
/// specified ID
macro_rules! generic_newtype_id_lookups {
    ($name:ident, $id:ident) => {
        impl<T> $name<T> {
            method_id_ref!(T, $id);
            method_id_mut!(T, $id);
        }

        impl<T: Copy> $name<T> {
            method_id!(T, $id);
        }
    };
}

/// Adds the [`AsRef`] trait to a newtype type
macro_rules! generic_newtype_asref {
    ($name:ident) => {
        impl<T> AsRef<$name<T>> for $name<T> {
            fn as_ref(&self) -> &$name<T> {
                self
            }
        }
    };
}

/// Adds the [`AsMut`] trait to a newtype type
macro_rules! generic_newtype_asmut {
    ($name:ident) => {
        impl<T> AsMut<$name<T>> for $name<T> {
            fn as_mut(&mut self) -> &mut $name<T> {
                self
            }
        }
    };
}

/// Adds the [`Deref`] trait to a newtype type that contains array data
macro_rules! generic_newtype_deref {
    ($name:ident, $n:expr) => {
        impl<T> Deref for $name<T> {
            type Target = [T; $n];
            fn deref(&self) -> &Self::Target {
                &self.0
            }
        }
    };
}

/// Adds the [`DerefMut`] trait to a newtype type that contains array data
macro_rules! generic_newtype_deref_mut {
    ($name:ident) => {
        impl<T> DerefMut for $name<T> {
            fn deref_mut(&mut self) -> &mut Self::Target {
                &mut self.0
            }
        }
    };
}

/// Adds the [`Index`] trait to a newtype type
macro_rules! generic_newtype_index {
    ($name:ident) => {
        impl<T, I> Index<I> for $name<T>
        where
            [T]: Index<I>,
        {
            type Output = <[T] as Index<I>>::Output;
            #[inline]
            fn index(&self, index: I) -> &Self::Output {
                Index::index(&self.0 as &[T], index)
            }
        }
    };
}

/// Adds the [`IndexMut`] trait to a newtype type
macro_rules! generic_newtype_index_mut {
    ($name:ident) => {
        impl<T, I> IndexMut<I> for $name<T>
        where
            [T]: IndexMut<I>,
        {
            #[inline]
            fn index_mut(&mut self, index: I) -> &mut Self::Output {
                IndexMut::index_mut(&mut self.0 as &mut [T], index)
            }
        }
    };
}

/// Adds the [`IntoIterator`] trait to a newtype type
macro_rules! generic_newtype_into_iter {
    ($name:ident, $n:expr) => {
        impl<T> IntoIterator for $name<T> {
            type Item = T;
            type IntoIter = std::array::IntoIter<Self::Item, $n>;

            fn into_iter(self) -> Self::IntoIter {
                self.0.into_iter()
            }
        }
    };
}

pub(crate) use generic_newtype_asmut;
pub(crate) use generic_newtype_asref;
pub(crate) use generic_newtype_deref;
pub(crate) use generic_newtype_deref_mut;
pub(crate) use generic_newtype_id_lookups;
pub(crate) use generic_newtype_index;
pub(crate) use generic_newtype_index_mut;
pub(crate) use generic_newtype_into_iter;
pub(crate) use generic_newtype_method_delegate;
pub(crate) use generic_newtype_unbox;
pub(crate) use method_id;
pub(crate) use method_id_mut;
pub(crate) use method_id_ref;
pub(crate) use methods_base;
pub(crate) use methods_clone;
pub(crate) use methods_copy;
pub(crate) use methods_partial_eq;