pipecircuit 0.0.5

use super::WarpTable;

/// Supplies the stable word used by a [`WarpTable`]'s primary index.
pub trait IndexKey: Copy + Eq {
    fn index_word(self) -> u64;
}

/// Describes one primary-indexed logical row and its aligned physical columns.
pub trait WarpTableRow: Sized {
    type Id: IndexKey;
    type Columns;
    type ColumnsCreationError;
    type Indexes;
    type IndexesCreationError;
    type IndexesInsertError: core::fmt::Debug;
    type PreparedIndexesInsert<'indexes>
    where
        Self: 'indexes;
    type IndexesRemoveError: core::fmt::Debug;
    type PreparedIndexesRemove<'indexes>
    where
        Self: 'indexes;
    type IndexesReplaceError: core::fmt::Debug;
    type PreparedIndexesReplace<'indexes>
    where
        Self: 'indexes;
    type Ref<'row>
    where
        Self: 'row;
    type Mut<'row>
    where
        Self: 'row;
    type Query<'table, Brand>
    where
        Self: 'table,
        Brand: 'table;
    type MutQuery<'table, Brand>
    where
        Self: 'table,
        Brand: 'table;
    type DetachedQuery<'indexes>
    where
        Self: 'indexes;

    fn try_new_columns(maximum_rows: usize) -> Result<Self::Columns, Self::ColumnsCreationError>;
    fn try_new_indexes(maximum_rows: usize) -> Result<Self::Indexes, Self::IndexesCreationError>;
    fn query<'table, Brand>(table: &'table WarpTable<Self, Brand>) -> Self::Query<'table, Brand>
    where
        Brand: 'table;
    fn query_mut<'table, Brand>(
        table: &'table mut WarpTable<Self, Brand>,
    ) -> Self::MutQuery<'table, Brand>
    where
        Brand: 'table;
    fn detached_query(indexes: &Self::Indexes) -> Self::DetachedQuery<'_>;

    /// Validates and reserves every index change without publishing any of it.
    ///
    /// Returning an error or dropping the prepared value must leave `indexes`
    /// unchanged. A successful preparation must make its commit infallible.
    fn try_prepare_indexes_insert<'indexes>(
        indexes: &'indexes mut Self::Indexes,
        row: &Self,
    ) -> Result<Self::PreparedIndexesInsert<'indexes>, Self::IndexesInsertError>;

    /// Publishes exactly one previously prepared index insertion.
    fn commit_indexes_insert(prepared: Self::PreparedIndexesInsert<'_>);

    /// Validates every index removal without publishing any of it.
    ///
    /// The supplied row reference is the logical row at `index`. Dropping the
    /// prepared value must leave all indexes unchanged.
    fn try_prepare_indexes_remove<'indexes>(
        indexes: &'indexes mut Self::Indexes,
        row: Self::Ref<'_>,
        index: usize,
    ) -> Result<Self::PreparedIndexesRemove<'indexes>, Self::IndexesRemoveError>;

    /// Publishes exactly one previously prepared index removal.
    fn commit_indexes_remove(prepared: Self::PreparedIndexesRemove<'_>);

    /// Validates every index move required by a row replacement.
    ///
    /// Dropping the prepared value must restore the indexes to their original
    /// observable state. A successful preparation makes commit infallible.
    fn try_prepare_indexes_replace<'indexes>(
        indexes: &'indexes mut Self::Indexes,
        current: Self::Ref<'_>,
        replacement: &Self,
        index: usize,
    ) -> Result<Self::PreparedIndexesReplace<'indexes>, Self::IndexesReplaceError>;

    /// Publishes exactly one previously prepared set of index moves.
    fn commit_indexes_replace(prepared: Self::PreparedIndexesReplace<'_>);
    fn append(columns: &mut Self::Columns, row: Self);

    /// Removes `index` from every column and reconstructs its row without allocating.
    fn swap_remove(columns: &mut Self::Columns, index: usize) -> Self;

    fn get<'row>(
        id: &'row Self::Id,
        columns: &'row Self::Columns,
        index: usize,
    ) -> Result<WarpTableRowGetOutcome<Self::Ref<'row>>, WarpTableRowGetError>;

    fn get_mut<'row>(
        id: &'row Self::Id,
        columns: &'row mut Self::Columns,
        indexes: &'row mut Self::Indexes,
        index: usize,
    ) -> Result<WarpTableRowGetOutcome<Self::Mut<'row>>, WarpTableRowGetError>;

    /// Replaces one complete logical row without changing column alignment.
    ///
    /// Implementations must leave every column unchanged when returning an error.
    fn replace(
        columns: &mut Self::Columns,
        index: usize,
        replacement: Self,
    ) -> Result<WarpTableRowReplaceOutcome<Self>, WarpTableRowReplaceError<Self>>;
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub enum WarpTableRowGetOutcome<Row> {
    Present { row: Row },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum WarpTableRowGetError {
    ColumnUnavailable { column: usize, row: usize },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub enum WarpTableRowReplaceOutcome<Row> {
    Replaced { previous: Row },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum WarpTableRowReplaceError<Row> {
    ColumnUnavailable {
        column: usize,
        row: usize,
        rejected: Row,
    },
}