ot-tools-io 0.8.0

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

//! Identifiers are used on generic collection types for panic-free access to elements of
//! the internal collections via `id*()` methods.
//!
//! # Example: [`PatternId`]
//!
//! ```
//! use ot_tools_io::identifiers::PatternId;
//! use ot_tools_io::BankFile;
//! use ot_tools_io::OtToolsIoError;
//!
//! fn main() -> Result<(), OtToolsIoError> {
//!     // mutable so we can demonstrate using `id_mut` methods
//!     let mut bank = BankFile::default();
//!
//!     // using variant by hand
//!     // -- pattern 1 (reference)
//!     bank.patterns.id_ref(&PatternId::One);
//!     // -- pattern 16 (mutable reference)
//!     bank.patterns.id_mut(&PatternId::Sixteen);
//!
//!     // lookup from *unsigned* integer values
//!     // failed conversions return an `OtToolsIoError::InvalidIndex` error for you to handle
//!     // -- pattern 1 (reference)
//!     bank.patterns.id_ref(&PatternId::try_from(0_usize)?);
//!     // -- pattern 16 (mutable reference)
//!     bank.patterns.id_mut(&PatternId::try_from(15_usize)?);
//!
//!     // iterate over variants
//!     for pattern_id in PatternId::iter() {
//!         bank.patterns.id_ref(&pattern_id);
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! # Special Case: [`SavedState`]
//!
//! In this library the [`SavedState`] enum "identifies" which instance you want to retrieve data
//! from.
//! One could argue that's not necessarily true.
//! But it feels right to me in terms of the way it gets used.
//!
//! Please read the documentation for [`SavedState`] for a more detailed explaination.
//!
//! # Special Case: [`PlaybackSlotId`]
//!
//! The identifier value for a slot is slightly different depending on which types you're using.
//!
//! Please read the documentation for [`PlaybackSlotId`] for a more detailed explaination.

use crate::OtToolsIoError;
use enum_iterator::{all, Sequence};
use ot_tools_io_derive::enum_try_from_u32_to_unsigned_types;
use std::cmp::Ordering;

/// Identifier values for the saved state of some data / files.
///
/// Most "identifier" types in this module use a series of alphanumeric characters to
/// identify an instance in the same manner that the Octatrack uses,
/// e.g. [`TrackId::One`] or [`BankId::A`]
///
/// This [`SavedState`] "identifier" type is different.
/// It will never be used with `id*()` methods to access the members of a collection.
/// It is used in two locations to model Octatrack behaviour:
/// - Accessing the saved or unsaved set of [`Parts`][parts] within a
///   [`BankFile`][bank] via the `parts()` method.
/// - Identifying which [`ProjectFile`][proj], [`BankFile`][bank], [`ArrangementFile`][arr] or
///   [`MarkersFile`][marks] should be read from / written to.
///
/// [parts]: crate::generics::Parts
/// [proj]: crate::ProjectFile
/// [bank]: crate::BankFile
/// [marks]: crate::MarkersFile
/// [arr]: crate::ArrangementFile
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq)]
pub enum SavedState {
    /// `*.work` files -- working copy
    ///
    /// # Note on File Creates/Writes
    ///
    /// ## Whole Project
    ///
    /// Data is written to all `*.work` files when either a `SYNC TO CARD` or a `SAVE PROJECT`
    /// operation is executed from the Octatrack's Project menu.
    ///
    // todo: check this
    /// ## Save Bank
    ///
    /// Data is written to `bank<ID>.work` file each time the `SAVE BANK` operation is executed from
    /// the Octatrack's Project menu.
    ///
    // todo: check this
    /// ## Save Arrangement
    ///
    /// Data is written to `arr<ID>.work` file when the `SAVE ARRANGEMENT` operation is executed
    /// from the Octatrack's Arranger sub-menu.
    ///
    Working,
    /// `*.strd` files -- restorable, stored copy.
    ///
    /// # Note on File Creates/Writes
    ///
    /// ## Whole Project
    ///
    /// Data is written to new `*.strd` files on the first `SAVE PROJECT` operation from
    /// the Octatrack's project menu.
    /// Subsequent `SAVE PROJECT` operations then save to those same files.
    ///
    // todo: check this
    /// ## Save Bank
    ///
    /// A `bank<ID>.strd` file is created when the `SAVE BANK` operation is first executed from
    /// the Octatrack's Project menu.
    /// Data is written to the `bank<ID>.strd` file each time the `SAVE BANK` operation is executed
    /// from the Octatrack's Project menu.
    ///
    // todo: check this
    /// ## Save Arrangement
    ///
    /// A `arr<ID>.strd` file is created when the `SAVE ARRANGEMENT` operation is first executed
    /// from the Octatrack's Arranger sub-menu.
    /// Data is written to the `arr<ID>.strd` file each time the `SAVE ARRANGEMENT` operation is
    /// executed from the Octatrack's Arranger sub-menu.
    Stored,
}

impl SavedState {
    /// Returns the relevant file extension for the saved state, for the files that support it.
    pub fn file_extension(&self) -> String {
        match self {
            SavedState::Working => "work".to_string(),
            SavedState::Stored => "strd".to_string(),
        }
    }
}

impl std::fmt::Display for SavedState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{self:#?} state")
    }
}

/// Identifier values for [`ArrangementFiles`][arrs], allowing for panic-free indexing via `id*` methods.
///
/// [arrs]: crate::generics::Arrangements
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum ArrId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
}

impl ArrId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Get the relevant file name path component for a [`crate::arrangements::ArrangementFile`]
    /// given the identifier's value
    pub fn file_name(&self) -> String {
        format!["arr{:0>2}", *self as u8 + 1].to_string()
    }

    /// Get the relevant file stem path component for a [`crate::arrangements::ArrangementFile`]
    /// given the identifier's value and some [`SavedState`]
    pub fn file_stem(&self, state: &SavedState) -> String {
        format![
            "{name}.{ext}",
            name = self.file_name(),
            ext = state.file_extension()
        ]
        .to_string()
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for ArrId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Arrangement {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for ArrId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Banks`][crate::generics::Banks], allowing for panic-free indexing via `id*` methods.
// todo: example (load blank project)
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum BankId {
    A = 0,
    B = 1,
    C = 2,
    D = 3,
    E = 4,
    F = 5,
    G = 6,
    H = 7,
    I = 8,
    J = 9,
    K = 10,
    L = 11,
    M = 12,
    N = 13,
    O = 14,
    P = 15,
}

impl BankId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Get the relevant file name path component for a [`crate::banks::BankFile`] given the
    /// identifier's value
    pub fn file_name(&self) -> String {
        format!["bank{:0>2}", self.as_index() + 1].to_string()
    }

    /// Get the relevant file stem path component for a [`crate::banks::BankFile`] given the
    /// identifier's value and some [`SavedState`]
    pub fn file_stem(&self, state: &SavedState) -> String {
        format![
            "{name}.{ext}",
            name = self.file_name(),
            ext = state.file_extension()
        ]
        .to_string()
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for BankId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Bank {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for BankId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::A),
            1 => Ok(Self::B),
            2 => Ok(Self::C),
            3 => Ok(Self::D),
            4 => Ok(Self::E),
            5 => Ok(Self::F),
            6 => Ok(Self::G),
            7 => Ok(Self::H),
            8 => Ok(Self::I),
            9 => Ok(Self::J),
            10 => Ok(Self::K),
            11 => Ok(Self::L),
            12 => Ok(Self::M),
            13 => Ok(Self::N),
            14 => Ok(Self::O),
            15 => Ok(Self::P),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Parts`][crate::generics::Parts], allowing for panic-free indexing via `id*` methods.
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum PartId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
}

impl PartId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for PartId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Part {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for PartId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Patterns`][crate::generics::Patterns], allowing for panic-free indexing via `id*` methods.
///
/// ```
/// use ot_tools_io::identifiers::PatternId;
/// use ot_tools_io::BankFile;
/// # use ot_tools_io::OtToolsIoError;
///
/// # fn main() -> Result<(), OtToolsIoError> {
/// // mutable so we can demonstrate using `id_mut` methods
/// let mut bank = BankFile::default();
///
/// // using variant by hand
/// // -- pattern 1 (reference)
/// bank.patterns.id_ref(&PatternId::One);
/// // -- pattern 16 (mutable reference)
/// bank.patterns.id_mut(&PatternId::Sixteen);
///
/// // lookup from an unsigned integer value
/// // -- pattern 1 (reference)
/// bank.patterns.id_ref(&PatternId::try_from(0_usize)?);
/// // -- pattern 16 (mutable reference)
/// bank.patterns.id_mut(&PatternId::try_from(15_usize)?);
///
/// // iterate over variants
/// for pattern_id in PatternId::iter() {
///     bank.patterns.id_ref(&pattern_id);
/// }
///
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum PatternId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
    Nine = 8,
    Ten = 9,
    Eleven = 10,
    Twelve = 11,
    Thirteen = 12,
    Fourteen = 13,
    Fifteen = 14,
    Sixteen = 15,
}

impl PatternId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for PatternId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Pattern {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for PatternId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            8 => Ok(Self::Nine),
            9 => Ok(Self::Ten),
            10 => Ok(Self::Eleven),
            11 => Ok(Self::Twelve),
            12 => Ok(Self::Thirteen),
            13 => Ok(Self::Fourteen),
            14 => Ok(Self::Fifteen),
            15 => Ok(Self::Sixteen),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Tracks`][crate::generics::Tracks], allowing for panic-free indexing via `id*` methods.
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum TrackId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
}

impl TrackId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for TrackId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Track {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for TrackId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Scenes`][crate::generics::Scenes], allowing for panic-free indexing via `id*` methods.
///
/// ```
/// use ot_tools_io::parts::{SceneXlvAssignments};
/// use ot_tools_io::identifiers::{SavedState, PartId, SceneId};
/// use ot_tools_io::BankFile;
/// # use ot_tools_io::OtToolsIoError;
///
/// # fn main() -> Result<(), OtToolsIoError> {
/// // mutable ref so we can demonstrate using `id_mut` methods
/// let mut bank = BankFile::default();
/// let part_one_working = bank
///     .parts_mut(&SavedState::Working)
///     .id_mut(&PartId::One);
///
/// // using variant by hand
/// // -- scene 1 (reference)
/// part_one_working.scene_xlvs.id_ref(&SceneId::One);
/// // -- scene 16 (mutable reference)
/// part_one_working.scene_xlvs.id_mut(&SceneId::Sixteen);
///
/// // lookup from an unsigned integer value
/// // failed conversions return an `OtToolsIoError::InvalidIndex` error for you to handle
/// // -- scene 1 (reference)
/// part_one_working.scene_xlvs.id_ref(&SceneId::try_from(0_usize)?);
/// // -- scene 16 (mutable reference)
/// part_one_working.scene_xlvs.id_mut(&SceneId::try_from(15_usize)?);
///
/// // iterate over variants
/// for scene_id in SceneId::iter() {
///     part_one_working.scene_xlvs.id_ref(&scene_id);
/// }
///
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum SceneId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
    Nine = 8,
    Ten = 9,
    Eleven = 10,
    Twelve = 11,
    Thirteen = 12,
    Fourteen = 13,
    Fifteen = 14,
    Sixteen = 15,
}

impl SceneId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for SceneId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Scene {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for SceneId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            8 => Ok(Self::Nine),
            9 => Ok(Self::Ten),
            10 => Ok(Self::Eleven),
            11 => Ok(Self::Twelve),
            12 => Ok(Self::Thirteen),
            13 => Ok(Self::Fourteen),
            14 => Ok(Self::Fifteen),
            15 => Ok(Self::Sixteen),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Trigs`][crate::generics::Trigs], allowing panic-free access to elements of
/// the internal collection via `id*()` methods.
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum TrigId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
    Nine = 8,
    Ten = 9,
    //
    Eleven = 10,
    Twelve = 11,
    Thirteen = 12,
    Fourteen = 13,
    Fifteen = 14,
    Sixteen = 15,
    Seventeen = 16,
    Eighteen = 17,
    Nineteen = 18,
    Twenty = 19,
    //
    TwentyOne = 20,
    TwentyTwo = 21,
    TwentyThree = 22,
    TwentyFour = 23,
    TwentyFive = 24,
    TwentySix = 25,
    TwentySeven = 26,
    TwentyEight = 27,
    TwentyNine = 28,
    Thirty = 29,
    //
    ThirtyOne = 30,
    ThirtyTwo = 31,
    ThirtyThree = 32,
    ThirtyFour = 33,
    ThirtyFive = 34,
    ThirtySix = 35,
    ThirtySeven = 36,
    ThirtyEight = 37,
    ThirtyNine = 38,
    Forty = 39,
    //
    FortyOne = 40,
    FortyTwo = 41,
    FortyThree = 42,
    FortyFour = 43,
    FortyFive = 44,
    FortySix = 45,
    FortySeven = 46,
    FortyEight = 47,
    FortyNine = 48,
    Fifty = 49,
    //
    FiftyOne = 50,
    FiftyTwo = 51,
    FiftyThree = 52,
    FiftyFour = 53,
    FiftyFive = 54,
    FiftySix = 55,
    FiftySeven = 56,
    FiftyEight = 57,
    FiftyNine = 58,
    Sixty = 59,
    //
    SixtyOne = 60,
    SixtyTwo = 61,
    SixtyThree = 62,
    SixtyFour = 63,
}

impl TrigId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for TrigId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            8 => Ok(Self::Nine),
            9 => Ok(Self::Ten),
            //
            10 => Ok(Self::Eleven),
            11 => Ok(Self::Twelve),
            12 => Ok(Self::Thirteen),
            13 => Ok(Self::Fourteen),
            14 => Ok(Self::Fifteen),
            15 => Ok(Self::Sixteen),
            16 => Ok(Self::Seventeen),
            17 => Ok(Self::Eighteen),
            18 => Ok(Self::Nineteen),
            19 => Ok(Self::Twenty),
            //
            20 => Ok(Self::TwentyOne),
            21 => Ok(Self::TwentyTwo),
            22 => Ok(Self::TwentyThree),
            23 => Ok(Self::TwentyFour),
            24 => Ok(Self::TwentyFive),
            25 => Ok(Self::TwentySix),
            26 => Ok(Self::TwentySeven),
            27 => Ok(Self::TwentyEight),
            28 => Ok(Self::TwentyNine),
            29 => Ok(Self::Thirty),
            //
            30 => Ok(Self::ThirtyOne),
            31 => Ok(Self::ThirtyTwo),
            32 => Ok(Self::ThirtyThree),
            33 => Ok(Self::ThirtyFour),
            34 => Ok(Self::ThirtyFive),
            35 => Ok(Self::ThirtySix),
            36 => Ok(Self::ThirtySeven),
            37 => Ok(Self::ThirtyEight),
            38 => Ok(Self::ThirtyNine),
            39 => Ok(Self::Forty),
            //
            40 => Ok(Self::FortyOne),
            41 => Ok(Self::FortyTwo),
            42 => Ok(Self::FortyThree),
            43 => Ok(Self::FortyFour),
            44 => Ok(Self::FortyFive),
            45 => Ok(Self::FortySix),
            46 => Ok(Self::FortySeven),
            47 => Ok(Self::FortyEight),
            48 => Ok(Self::FortyNine),
            49 => Ok(Self::Fifty),
            //
            50 => Ok(Self::FiftyOne),
            51 => Ok(Self::FiftyTwo),
            52 => Ok(Self::FiftyThree),
            53 => Ok(Self::FiftyFour),
            54 => Ok(Self::FiftyFive),
            55 => Ok(Self::FiftySix),
            56 => Ok(Self::FiftySeven),
            57 => Ok(Self::FiftyEight),
            58 => Ok(Self::FiftyNine),
            59 => Ok(Self::Sixty),
            //
            60 => Ok(Self::SixtyOne),
            61 => Ok(Self::SixtyTwo),
            62 => Ok(Self::SixtyThree),
            63 => Ok(Self::SixtyFour),
            //
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`Slices`][crate::generics::Slices], allowing panic-free access to
/// elements of the internal collection via `id*()` methods.
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum SliceId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
    Nine = 8,
    Ten = 9,
    //
    Eleven = 10,
    Twelve = 11,
    Thirteen = 12,
    Fourteen = 13,
    Fifteen = 14,
    Sixteen = 15,
    Seventeen = 16,
    Eighteen = 17,
    Nineteen = 18,
    Twenty = 19,
    //
    TwentyOne = 20,
    TwentyTwo = 21,
    TwentyThree = 22,
    TwentyFour = 23,
    TwentyFive = 24,
    TwentySix = 25,
    TwentySeven = 26,
    TwentyEight = 27,
    TwentyNine = 28,
    Thirty = 29,
    //
    ThirtyOne = 30,
    ThirtyTwo = 31,
    ThirtyThree = 32,
    ThirtyFour = 33,
    ThirtyFive = 34,
    ThirtySix = 35,
    ThirtySeven = 36,
    ThirtyEight = 37,
    ThirtyNine = 38,
    Forty = 39,
    //
    FortyOne = 40,
    FortyTwo = 41,
    FortyThree = 42,
    FortyFour = 43,
    FortyFive = 44,
    FortySix = 45,
    FortySeven = 46,
    FortyEight = 47,
    FortyNine = 48,
    Fifty = 49,
    //
    FiftyOne = 50,
    FiftyTwo = 51,
    FiftyThree = 52,
    FiftyFour = 53,
    FiftyFive = 54,
    FiftySix = 55,
    FiftySeven = 56,
    FiftyEight = 57,
    FiftyNine = 58,
    Sixty = 59,
    //
    SixtyOne = 60,
    SixtyTwo = 61,
    SixtyThree = 62,
    SixtyFour = 63,
}

impl SliceId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for SliceId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            8 => Ok(Self::Nine),
            9 => Ok(Self::Ten),
            //
            10 => Ok(Self::Eleven),
            11 => Ok(Self::Twelve),
            12 => Ok(Self::Thirteen),
            13 => Ok(Self::Fourteen),
            14 => Ok(Self::Fifteen),
            15 => Ok(Self::Sixteen),
            16 => Ok(Self::Seventeen),
            17 => Ok(Self::Eighteen),
            18 => Ok(Self::Nineteen),
            19 => Ok(Self::Twenty),
            //
            20 => Ok(Self::TwentyOne),
            21 => Ok(Self::TwentyTwo),
            22 => Ok(Self::TwentyThree),
            23 => Ok(Self::TwentyFour),
            24 => Ok(Self::TwentyFive),
            25 => Ok(Self::TwentySix),
            26 => Ok(Self::TwentySeven),
            27 => Ok(Self::TwentyEight),
            28 => Ok(Self::TwentyNine),
            29 => Ok(Self::Thirty),
            //
            30 => Ok(Self::ThirtyOne),
            31 => Ok(Self::ThirtyTwo),
            32 => Ok(Self::ThirtyThree),
            33 => Ok(Self::ThirtyFour),
            34 => Ok(Self::ThirtyFive),
            35 => Ok(Self::ThirtySix),
            36 => Ok(Self::ThirtySeven),
            37 => Ok(Self::ThirtyEight),
            38 => Ok(Self::ThirtyNine),
            39 => Ok(Self::Forty),
            //
            40 => Ok(Self::FortyOne),
            41 => Ok(Self::FortyTwo),
            42 => Ok(Self::FortyThree),
            43 => Ok(Self::FortyFour),
            44 => Ok(Self::FortyFive),
            45 => Ok(Self::FortySix),
            46 => Ok(Self::FortySeven),
            47 => Ok(Self::FortyEight),
            48 => Ok(Self::FortyNine),
            49 => Ok(Self::Fifty),
            //
            50 => Ok(Self::FiftyOne),
            51 => Ok(Self::FiftyTwo),
            52 => Ok(Self::FiftyThree),
            53 => Ok(Self::FiftyFour),
            54 => Ok(Self::FiftyFive),
            55 => Ok(Self::FiftySix),
            56 => Ok(Self::FiftySeven),
            57 => Ok(Self::FiftyEight),
            58 => Ok(Self::FiftyNine),
            59 => Ok(Self::Sixty),
            //
            60 => Ok(Self::SixtyOne),
            61 => Ok(Self::SixtyTwo),
            62 => Ok(Self::SixtyThree),
            63 => Ok(Self::SixtyFour),
            //
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}

/// Identifier values for [`PlaybackSlots`][crate::generics::PlaybackSlots].
/// Please read the documentation to understand the special cases related to this type, why it
/// currently exists, why it may not exist for much longer and examples etc.
///
/// # Why is [`PlaybackSlotId`] a `struct` newtype and not an `enum` like every other "ID" type?
///
/// Honestly, because typing out values `SlotId::One` through to `SlotId::OneTwentyEight` was just
/// not something i have been remotely keen on doing.
/// So, for now this is staying as a newtype `struct` and needs to be used slightly differently to
/// the other ID types.
///
/// # Explainer
///
/// One of the frustrating things about slot data is the fact that there are three different
/// indexing or "identifier" values for looking up or referencing a "slot".
/// Making life more complicated -- each special case is related to a completely different data file.
///
/// The first usage is the value used by both [`AudioTrackMachineSlot`][2] and
/// [`AudioTrackParameterLocks`][3] to indicate the slot currently in use by an audio track.
/// This first value is a **ZERO**-indexed `u8` **INDEX** value.
///
/// The second usage is the array data storing [`SlotMarkers`][4] data.
/// The "identifier" here is not a value in the actual data as such.
/// Rather we do standard rust array element index lookup with a **ZERO**-indexed `usize` **INDEX**
/// value.
///
/// The third usage is the 'setttings' data stored as a [`SlotAttributes`][5] in a
/// [`crate::ProjectFile`].
/// The raw data is a **ONE**-indexed `String` value (the whole file is string data),
/// and this library currently parses this value into a `u8` **ID** value (_not_ an **INDEX** value!).
///
/// Just to summarise that to make the point absolutely clear -- the three different
/// indexing/"identifier" types are
/// 1. zero-index `u8` -- an INDEX value
/// 2. zero-index `usize` -- an INDEX value
/// 3. one-index `String` -> one-index `u8` -- an ID value (Slot ID in [`SlotAttributes`][5])
///
/// The net result of this is that you sometimes have to track THREE different index/ID values of a
/// slot depending on what you're trying to do.
/// ```compile_fail
/// // some ProjectFile one-index slot id value
/// let slot_id = slot_attr.slot_id;
///
/// // convert to bank slot data zero-index u8
/// // -- btw, I hope you didn't accidentally set the `slot_id` field to zero by accident!
/// // -- otherwise you'll panic here!
/// let slot_bank_index = slot_id - 1;
///
/// // convert to a zero-index `usize` for accessing markers data
/// // -- same panic issue applies!
/// let slot_markers_index = (slot_id - 1) as usize;
/// ```
///
/// This starts becoming a MASSIVE headache the more you come up against it more than once.
/// It is VERY easy to lose track of which variable tracks which index if you're not super explicit
/// with your naming conventions.
/// I lost count of the number of times I've had to re-read a massive function to work out if
/// `slot_idx` is zero-index or one-index.
///
/// So, the current implementation for [`PlaybackSlotId`] is a quick initial attempt to address this issue
/// (the idea then spawned the rest of the "identifier" types).
///
/// # Using [`PlaybackSlotId`]
///
/// You are currently required to manually convert from one of the types mentioned above into a
/// [`PlaybackSlotId`] type, which means being aware of which type you are converting from.
///
/// There are two methods for converting from raw data values:
/// - `from_index` -- use this to get a [`PlaybackSlotId`] from a zero-index value
/// - `from_id` -- use this to get a [`PlaybackSlotId`] from a one-index value
///
/// Note that both methods return an `Option<SlotId>` to handle the case where you provide a bad
/// input value that exceeds the maximum possible index/id value
/// -- see the [`PlaybackSlotId::MAX_INDEX`] and [`PlaybackSlotId::MAX_ID`] const values.
///
/// Once you have a [`PlaybackSlotId`], there are two similar methods for converting back to a raw data
/// value:
/// - `as_index` -- use this to get a zero-index `usize` value
/// - `as_id` -- use this to get a one-index `u8` value
///
/// ```
/// # use ot_tools_io::identifiers::PlaybackSlotId;
/// // one-index ID from ProjectFile data
/// // into a zero-index INDEX for bank data/markers array indexing
/// assert_eq!(PlaybackSlotId::from_id(100).unwrap().as_index(), 99);
///
/// // zero-index index value from bank data or the markers array index
/// // into a one-index ID value for ProjectFile data
/// assert_eq!(PlaybackSlotId::from_index(99).unwrap().as_id(), 100);
/// ```
///
/// None of this is ideal, but it's definitely an improvement on what it was like before!
/// You at least end up with a standard [`PlaybackSlotId`] type once you've converted the appropriate value!
/// As explained above, previously you'd just have to remember if some variable was zero or one
/// indexed.
/// At least now you just need to know whether the function/method/specific code block where you're
/// passing/using the [`PlaybackSlotId`] type needs a one-index ID or a zero-index Index.
///
/// # Future Work
///
/// In future, I would like to implement [`serde::Serialize`] and [`serde::Deserialize`] more
/// fully for [`AudioTrackMachineSlot`][2], [`AudioTrackParameterLocks`][3] and [`SlotAttributes`][5];
/// with the intention being that the relevant slot ID field(s) of each type deserializes to this
/// [`PlaybackSlotId`] type without having to manually convert it in downstream code.
/// Additionally, I may follow on from the recent work on Recording Buffers
/// (using the [`crate::generics::Tracks`] generic collection helper instead of bundling them in with Flex Slots)
/// and break from the convention of trying to keep all data as close to raw binary values as
/// possible, parsing the `SLOT_ID` field in [`SlotAttributes`][5] data as zero-index.
///
/// However, that work is being left to the future for now, although it's hopefully going to come in
/// one of the next major releases (if not the next major release).
///
/// [2]: crate::parts::AudioTrackMachineSlot
/// [3]: crate::patterns::AudioTrackParameterLocks
/// [4]: crate::markers::MarkersFile
/// [5]: crate::projects::SlotAttributes
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct PlaybackSlotId(usize);

impl PlaybackSlotId {
    // DOES NOT SUPPORT RECORDER SLOTS!
    pub const MAX_INDEX: usize = 127;
    pub const MAX_ID: usize = 128;

    /// Read a zero-index INDEX value to get a [`PlaybackSlotId`].
    /// INDEX values are used in certain [`crate::banks::BankFile`] subtypes and as indices for the
    /// markers arrays in [`crate::markers::MarkersFile`]
    pub fn from_index(v: usize) -> Option<Self> {
        if v > Self::MAX_INDEX {
            None
        } else {
            Some(PlaybackSlotId(v))
        }
    }

    /// Read a one-index ID value to get a [`PlaybackSlotId`].
    /// The ID values is used in [`crate::projects::SlotAttributes`].
    pub fn from_id(v: u8) -> Option<Self> {
        if v == 0 || v > Self::MAX_ID as u8 {
            None
        } else {
            Some(PlaybackSlotId(v as usize - 1))
        }
    }

    /// Return a zero-index INDEX value for the [`PlaybackSlotId`], used in certain
    /// [`crate::banks::BankFile`] subtypes and to index the markers arrays in
    /// [`crate::markers::MarkersFile`]
    pub fn as_index(&self) -> usize {
        self.0
    }

    /// Return a one-index ID value for the [`PlaybackSlotId`], used in [`crate::projects::SlotAttributes`]
    pub fn as_id(&self) -> u8 {
        (self.0 + 1) as u8
    }

    /// Iterate over all possible INDEX values for a [`PlaybackSlotId`]
    pub fn iter_all() -> impl Iterator<Item = Self> {
        (0..(Self::MAX_INDEX + 1)).flat_map(Self::from_index)
    }
}

impl std::fmt::Display for PlaybackSlotId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "index={:#?} id={:#?}", self.as_index(), self.as_id())
    }
}

impl PartialOrd for PlaybackSlotId {
    fn partial_cmp(&self, other: &PlaybackSlotId) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for PlaybackSlotId {
    fn cmp(&self, other: &Self) -> Ordering {
        if self.0 > other.0 {
            Ordering::Greater
        } else if self.0 < other.0 {
            Ordering::Less
        } else {
            Ordering::Equal
        }
    }
}

/// Identifier values for [`RecordingBufferSlots`][crate::generics::RecordingBufferSlots],
/// allowing for panic-free indexing via `id*` methods.
#[derive(Clone, Copy, PartialEq, Debug, Hash, PartialOrd, Ord, Eq, Sequence)]
#[repr(u8)]
pub enum RecBufId {
    One = 0,
    Two = 1,
    Three = 2,
    Four = 3,
    Five = 4,
    Six = 5,
    Seven = 6,
    Eight = 7,
}

impl RecBufId {
    /// Get the identifier variant as a zero-indexed integer for raw array indexing
    pub fn as_index(&self) -> usize {
        *self as usize
    }

    /// Iterate over all possible enum variants
    pub fn iter() -> impl Iterator<Item = Self> {
        all::<Self>()
    }
}

impl std::fmt::Display for RecBufId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Track {self:#?}")
    }
}

#[enum_try_from_u32_to_unsigned_types]
impl TryFrom<u32> for RecBufId {
    type Error = OtToolsIoError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::One),
            1 => Ok(Self::Two),
            2 => Ok(Self::Three),
            3 => Ok(Self::Four),
            4 => Ok(Self::Five),
            5 => Ok(Self::Six),
            6 => Ok(Self::Seven),
            7 => Ok(Self::Eight),
            _ => Err(OtToolsIoError::InvalidIndex),
        }
    }
}