ot-tools-io 0.11.3

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

//! Types and implementations related to the [`SlotMarkers`] type.

use crate::generics::Slices;
use crate::slices::Slice;
use crate::traits::SwapBytes;
use crate::Defaults;
use crate::{IsDefault, OtToolsIoError, SampleSettingsFile};
use ot_tools_io_derive::{
    ArrayDefaults, AsMutDerive, AsRefDerive, BoxedArrayDefaults, IsDefaultCheck,
};
use serde::{Deserialize, Serialize};
use std::array::from_fn;
use thiserror::Error;

/// Errors specific to [`SlotMarkers`].
///
/// Most of the time this will be casted into an [`OtToolsIoError`] instance in a return type.
#[derive(Debug, Error)]
pub enum SlotMarkersError {
    /// There's a problem with the loop point value.
    /// Likely outside the accepted bounds of the `trim_start` and `trim_end` fields.
    #[error("invalid loop point: {value}")]
    Loop { value: u32 },
    /// There's a problem with one of the trim values.
    /// Usually one of `trim_start`/`trim_end` is before/after the other when it shouldn't be.
    #[error("invalid trim: start={start} end={end}")]
    Trim { start: u32, end: u32 },
    /// There's a problem with the `slice_count` field.
    #[error("invalid slice count: {value}")]
    SliceCount { value: u32 },
}

/// Slot playback trigger points/markers.
/// Generally, data related to trim, looping and slices for each sample slot.
/// Other slot settings like quantization/time-stretch/loop modes are stored in the
/// [`SlotAttributes`][attr] type for the specific slot.
///
/// # Type Name
///
/// The Octatrack manual refers to "markers" in a lot of places.
///
/// I prefixed the name with `Slot*` to make it clear this type is related to a sample slot.
///
/// # Converting to/from [`SampleSettingsFile`]
///
/// [`SlotMarkers`]s can be converted from/to [`SampleSettingsFile`] using the information from the
/// below table
///
/// | From | To | Via |
/// | ---- | ---- | ---- |
/// | [`SampleSettingsFile`] | [`SlotMarkers`] | [`SlotMarkers::from`] |
/// | `(SlotAttributes, SlotMarkers)` | [`SampleSettingsFile`] | [`SampleSettingsFile::from`] |
///
/// [attr]: crate::projects::SlotAttributes
#[derive(
    Copy,
    Clone,
    Debug,
    Default,
    Eq,
    Hash,
    Ord,
    PartialEq,
    PartialOrd,
    Serialize,
    Deserialize,
    AsMutDerive,
    AsRefDerive,
    IsDefaultCheck,
    ArrayDefaults,
    BoxedArrayDefaults,
)]
pub struct SlotMarkers {
    /// Sample playback trim start point.
    /// Measured in number of audio samples.
    ///
    /// ## Field Name
    ///
    /// Should be renamed to `trim_start_point` as this is what the Octatrack manual refers to
    ///
    /// > Set the start point with the **A** knob.
    /// > A start point is indicated by an “S” marker.
    /// > The sample will start to play from this position.
    /// >
    /// > -- page 81
    ///
    /// # Validation
    ///
    /// `trim_end` must be less than `trim_offset`.
    ///
    /// If the slot isn't initialized then `trim_offset` must be zero.
    pub trim_offset: u32,

    /// Sample playback trim end.
    /// Measured in number of samples of audio array.
    ///
    /// ## Field Name
    ///
    /// Should be renamed to `trim_end_point` as this is what the Octatrack manual refers to
    ///
    /// > Set the end point with the **C** knob.
    /// > An end point is indicated by an “E” marker.
    /// > The sample will stop playing when reaching the end point given no loop point is set.
    /// >
    /// > -- page 82
    ///
    /// # Validation
    ///
    /// `trim_end` must be greater than `trim_offset`.
    ///
    /// If the slot isn't initialized then `trim_end` must be zero.
    pub trim_end: u32,

    /// Sample playback loop start point.
    /// Measured in number of audio samples.
    ///
    /// ## Field Name
    ///
    /// Should be renamed to `loop_point` as this is what the Octatrack manual refers to
    ///
    /// > A loop is indicated by an “L” marker.
    /// > Move the loop point by turning the **B** knob.
    /// >
    /// > -- page 81
    ///
    /// # No Disabling
    ///
    /// It is not possible to disable the main `loop_point` of a slot.
    /// Do not use the [`SLICE_LOOP_POINT_DISABLED`][loop_off] value here.
    ///
    /// # Validation
    ///
    /// If the slot has been initialized, then
    /// - `loop_point` must be greater than or equal to `trim_offset`.
    /// - `loop_point` must be less than `trim_end`.
    ///
    /// If the slot isn't initialized then `loop_point` must be zero.
    ///
    /// [loop_off]: crate::slices::SLICE_LOOP_POINT_DISABLED
    pub loop_point: u32,

    /// Array of [`Slice`] markers.
    /// See the documentation for [`Slice`]s for more information.
    ///
    /// ## Slice marker points outside slot trim range
    ///
    /// This is permitted by the Octatrack.
    /// You can have [`Slice`] `trim_start` and `trim_end` values outside the bounds of the slots's
    /// main trim range.
    ///
    /// ## Validation
    ///
    /// Handled by calling the [`Slice::validate`] method.
    pub slices: Slices<Slice>,

    /// Number of initialized [`Slice`] in the slice array.
    /// An 'initialized' [`Slice`] has non-zero values
    /// -- the [`Slice`] loop_point must be non-zero or the `trim_end` field must be non-zero.
    ///
    /// ## Validation
    ///
    /// If the slot isn't initialized then `slice_count` must be zero.
    pub slice_count: u32,
}

impl SwapBytes for SlotMarkers {
    fn swap_bytes(self) -> Self {
        let mut slices = self.slices;

        for (i, slice) in self.slices.iter().enumerate() {
            slices[i] = slice.swap_bytes();
        }

        Self {
            trim_offset: self.trim_offset.swap_bytes(),
            trim_end: self.trim_end.swap_bytes(),
            loop_point: self.loop_point.swap_bytes(),
            slices,
            slice_count: self.slice_count.swap_bytes(),
        }
    }
}

impl SlotMarkers {
    /// Creates a new initialised [`SlotMarkers`] instance.
    /// Use the [`SlotMarkers::default`] method to create an un-initialized instance.
    ///
    /// `trim_start` and `trim_end` are required arguments.
    /// A slot must always have trim values.
    /// This also ensures the method can set a valid `loop_point` when the `loop_point` argument
    /// value is not provided (set to the `trim_start` value).
    ///
    /// This method has the benefit of always calling the [`SlotMarkers::validate`] during
    /// instantiation.
    ///
    /// Sometimes it may be less cumbersome to combine struct update syntax with the
    /// `Default::default()` trait method
    /// ```
    /// # use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::markers::SlotMarkers;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let x = SlotMarkers { trim_end: 100, ..Default::default() };
    /// x.validate()?;
    /// # Ok(()) }
    /// ```
    ///
    /// # Valid Example
    /// ```
    /// # use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::markers::SlotMarkers;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let x = SlotMarkers::new(100, 400, Some(200), None)?;
    /// # Ok(()) }
    /// ```
    pub fn new(
        trim_start: u32,
        trim_end: u32,
        loop_point: Option<u32>,
        slices: Option<Slices<Slice>>,
    ) -> Result<Self, OtToolsIoError> {
        let slices = slices.unwrap_or_default();
        let slice_count = slices.iter().filter(|x| !x.is_default()).count() as u32;

        let new = Self {
            trim_offset: trim_start,
            trim_end,
            loop_point: loop_point.unwrap_or(trim_start),
            slices,
            slice_count,
        };
        new.validate()?;
        Ok(new)
    }

    /// Runs a series of validation checks on the field values for an instance of the type.
    ///
    /// Will return an appropriate error if a problem is discovered with a field's value.
    ///
    /// Read through the fields on [`SlotMarkers`] to find out which ones are checked and how
    /// they are checked.
    ///
    /// # Examples
    /// ```
    /// # use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::types::{SlotMarkers, Slices, Slice};
    /// use ot_tools_io::slices::SLICE_LOOP_POINT_DISABLED;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// // uninitialized is always valid
    /// SlotMarkers::default().validate()?;
    ///
    /// // loop point within trim range
    /// SlotMarkers { loop_point: 100, trim_offset: 100, trim_end: 500, ..Default::default() }.validate()?;
    /// SlotMarkers { loop_point: 499, trim_offset: 100, trim_end: 500, ..Default::default() }.validate()?;
    ///
    /// let mut slices = Slices::<Slice>::default();
    ///
    /// // valid slice trim and loop values outside trim range are accepted
    /// slices[0] = Slice { trim_start: 300, trim_end: 500, loop_start: 300 };
    ///
    /// SlotMarkers {
    ///     trim_offset: 100, trim_end: 200, loop_point: 100, slice_count: 1, slices
    /// }.validate()?;
    /// # Ok(()) }
    /// ```
    pub fn validate(&self) -> Result<(), OtToolsIoError> {
        // default should always be valid
        if self.is_default() {
            return Ok(());
        }

        if self.trim_offset > self.trim_end {
            return Err(SlotMarkersError::Trim {
                start: self.trim_offset,
                end: self.trim_end,
            }
            .into());
        }

        if !crate::loop_point_is_in_trim_range(self.loop_point, self.trim_offset, self.trim_end) {
            return Err(SlotMarkersError::Loop {
                value: self.loop_point,
            }
            .into());
        }

        let slice_count = self.slices.iter().filter(|x| !x.is_default()).count();
        if self.slice_count != slice_count as u32 {
            return Err(SlotMarkersError::SliceCount {
                value: self.slice_count,
            }
            .into());
        }

        for slice in self.slices {
            slice.validate()?;
        }

        Ok(())
    }

    /// "De-inits" all fields to zero values.
    pub fn deinit(&mut self) {
        self.trim_offset = 0;
        self.trim_end = 0;
        self.loop_point = 0;
        self.slice_count = 0;
        for slice in self.slices.iter_mut() {
            slice.deinit();
        }
    }
}

impl<T> From<T> for SlotMarkers
where
    T: AsRef<SampleSettingsFile>,
{
    fn from(value: T) -> Self {
        let value = value.as_ref();
        SlotMarkers {
            trim_offset: value.trim_start,
            trim_end: value.trim_end,
            loop_point: value.loop_start,
            slices: value.slices,
            slice_count: value.slices_len,
        }
    }
}

#[cfg(test)]
mod deinit {
    use crate::markers::SlotMarkers;
    use crate::{IsDefault, OtToolsIoError};
    #[test]
    fn ok() -> Result<(), OtToolsIoError> {
        let mut x = SlotMarkers::new(100, 200, Some(150), None)?;
        x.deinit();
        assert!(x.is_default());
        Ok(())
    }
}

#[cfg(test)]
mod new {
    use super::{SlotMarkers, SlotMarkersError};
    use crate::generics::Slices;
    use crate::slices::Slice;
    use crate::OtToolsIoError;
    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        assert_eq!(
            SlotMarkers::new(0, 100, None, None)?,
            SlotMarkers {
                trim_offset: 0,
                trim_end: 100,
                loop_point: 0,
                slices: Slices::<Slice>::default(),
                slice_count: 0,
            },
        );
        Ok(())
    }

    #[test]
    fn invalid_trim_offset() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers::new(100, 0, None, None);
        assert_eq!(
            x.unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::Trim { start: 100, end: 0 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_loop_point() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers::new(0, 0, Some(100), None);
        assert_eq!(
            x.unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::Loop { value: 100 }).to_string()
        );
        Ok(())
    }
}

#[cfg(test)]
mod validate {
    use super::{SlotMarkers, SlotMarkersError};
    use crate::generics::Slices;
    use crate::slices::{Slice, SliceError, SLICE_LOOP_POINT_DISABLED};
    use crate::OtToolsIoError;

    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        assert!(SlotMarkers::default().validate().is_ok());
        Ok(())
    }

    #[test]
    fn invalid_trim() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers {
            trim_offset: 100,
            trim_end: 0,
            ..SlotMarkers::default()
        };
        assert_eq!(
            x.validate().unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::Trim { start: 100, end: 0 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_loop_point_disabled() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers {
            loop_point: SLICE_LOOP_POINT_DISABLED,
            ..Default::default()
        }
        .validate();
        assert_eq!(
            x.unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::Loop {
                value: SLICE_LOOP_POINT_DISABLED
            })
            .to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_loop_point_before_trim_range() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers {
            loop_point: 0,
            trim_offset: 100,
            trim_end: 200,
            ..SlotMarkers::default()
        };
        assert_eq!(
            x.validate().unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::Loop { value: 0 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_loop_point_after_trim_range() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers {
            loop_point: 100,
            trim_end: 100,
            ..SlotMarkers::default()
        };
        assert_eq!(
            x.validate().unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::Loop { value: 100 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_slice_count_no_slices() -> Result<(), OtToolsIoError> {
        let x = SlotMarkers {
            slice_count: 100,
            trim_end: 1000,
            ..SlotMarkers::default()
        };
        assert_eq!(
            x.validate().unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::SliceCount { value: 100 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_slice_count_one_slice() -> Result<(), OtToolsIoError> {
        let mut slices = Slices::<Slice>::default();
        slices[0] = Slice {
            trim_start: 100,
            trim_end: 200,
            loop_start: 100,
        };

        let x = SlotMarkers {
            trim_offset: 100,
            trim_end: 200,
            loop_point: 100,
            slice_count: 10,
            slices,
        }
        .validate();

        assert_eq!(
            x.unwrap_err().to_string(),
            OtToolsIoError::Markers(SlotMarkersError::SliceCount { value: 10 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_slice_loop_point_oob() -> Result<(), OtToolsIoError> {
        let mut slices = Slices::<Slice>::default();
        slices[0] = Slice {
            trim_start: 100,
            trim_end: 200,
            loop_start: 0,
        };

        let x = SlotMarkers {
            trim_offset: 100,
            trim_end: 200,
            loop_point: 100,
            slice_count: 1,
            slices,
        }
        .validate();

        assert_eq!(
            x.unwrap_err().to_string(),
            OtToolsIoError::Slice(SliceError::LoopPoint { value: 0 }).to_string()
        );
        Ok(())
    }

    #[test]
    fn valid_slice_out_of_trim_range() -> Result<(), OtToolsIoError> {
        let mut slices = Slices::<Slice>::default();
        slices[0] = Slice {
            trim_start: 300,
            trim_end: 500,
            loop_start: 300,
        };

        let x = SlotMarkers {
            trim_offset: 100,
            trim_end: 200,
            loop_point: 100,
            slice_count: 1,
            slices,
        }
        .validate();

        assert!(x.is_ok());
        Ok(())
    }
}