tabled/settings/split/

mod.rs

//! This module contains a [`Split`] setting which is used to
//! format the cells of a [`Table`] by a provided index, direction, behavior, and display preference.
//!
//! [`Table`]: crate::Table

use core::ops::Range;

use crate::grid::{
    config::Position,
    records::{ExactRecords, PeekableRecords, Records, Resizable},
};

use super::TableOption;

#[derive(Debug, Clone, Copy)]
enum Direction {
    Column,
    Row,
}

#[derive(Debug, Clone, Copy)]
enum Behavior {
    Concat,
    Zip,
}

#[derive(Debug, Clone, Copy, PartialEq)]
enum Display {
    Clean,
    Retain,
}

/// Returns a new [`Table`] formatted with several optional parameters.
///
/// The required index parameter determines how many columns/rows a table will be redistributed into.
///
/// - index
/// - direction
/// - behavior
/// - display
///
/// #### Directions
///
/// Direction functions are the entry point for the `Split` setting.
///
/// There are two directions available: `column` and `row`.
///
/// ```rust
/// use std::iter::FromIterator;
/// use tabled::{Table, settings::split::Split};
///
/// let mut table = Table::from_iter(['a'..='z']);
/// table.with(Split::column(12));
/// table.with(Split::row(2));
/// ```
///
/// ```text
/// ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
/// │ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │ z │
/// └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
/// ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
/// │ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │
/// ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
/// │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │
/// ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
/// │ y │ z │   │   │   │   │   │   │   │   │   │   │<- y and z act as anchors to new empty cells
/// └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘   to conform to the new shape
/// ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
/// │ a │ y │ b │ z │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │
/// ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤<- Display::Clean removes empty cells that would be anchors otherwise
/// │ m │   │ n │   │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │
/// └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
///       ^anchors^
/// ```
///
///
/// #### Behaviors
///
/// Behaviors determine how cells attempt to conform to the new tables shape.
///
/// There are two behaviors available: `zip` and `concat`.
///
/// `zip` is the default behavior.
///
/// ```rust
/// use std::iter::FromIterator;
/// use tabled::{Table, settings::split::Split};
///
/// let mut table = Table::from_iter(['a'..='z']);
/// table.with(Split::column(2).concat());
/// table.with(Split::column(2).zip());
/// ```
///
/// ```text
///                                                 +---+---+
///                                                 | a | b |
///                                                 +---+---+
/// +---+---+---+---+---+                           | f | g |
/// | a | b | c | d | e | Split::column(2).concat() +---+---+
/// +---+---+---+---+---+           =>              | c | d |
/// | f | g | h | i | j |                           +---+---+
/// +---+---+---+---+---+                           | h | i |
///                                                 +---+---+
///                                                 | e |   |
///                                                 +---+---+
///                                                 | j |   |
///                                                 +---+---+
///
///                   sect 3                        +---+---+
///  sect 1   sect 2 (anchors)                      | a | b |
///   /   \   /   \   /   \                         +---+---+
/// +---+---+---+---+---+                           | c | d |
/// | a | b | c | d | e |  Split::column(2).zip()   +---+---+
/// +---+---+---+---+---+           =>              | e |   |
/// | f | g | h | i | j |                           +---+---+
/// +---+---+---+---+---+                           | f | g |
///                                                 +---+---+
///                                                 | h | i |
///                                                 +---+---+
///                                                 | j |   |
///                                                 +---+---+
/// ```
///
/// #### Displays
///
/// Display functions give the user the choice to `retain` or `clean` empty sections in a `Split` table result.
///
/// - `retain` does not filter any existing or newly added cells when conforming to a new shape.
///
/// - `clean` filters out empty columns/rows from the output and prevents empty cells from acting as anchors to newly inserted cells.
///
/// `clean` is the default `Display`.
///
/// ```rust
/// use std::iter::FromIterator;
/// use tabled::{
///     settings::{split::Split, style::Style},
///     Table,
/// };
/// let mut table = Table::from_iter(['a'..='z']);
/// table.with(Split::column(25)).with(Style::modern());
/// table.clone().with(Split::column(1).concat().retain());
/// table.clone().with(Split::column(1).concat()); // .clean() is not necessary as it is the default display property
/// ```
///
/// ```text
/// ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
/// │ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │
/// ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
/// │ z │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │   │<- lots of extra cells generated
/// └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
/// ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
/// │ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │ z │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │  │
/// └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
/// ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ^ cells retained during concatenation
/// │ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │ z │
/// └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘<- cells removed during concatenation
/// ```
///
///
/// # Example
///
/// ```rust
/// use std::iter::FromIterator;
/// use tabled::{
///     settings::split::Split,
///     Table,
/// };
///
/// let mut table = Table::from_iter(['a'..='z']);
/// let table = table.with(Split::column(4)).to_string();
///
/// assert_eq!(table, "+---+---+---+---+\n\
///                    | a | b | c | d |\n\
///                    +---+---+---+---+\n\
///                    | e | f | g | h |\n\
///                    +---+---+---+---+\n\
///                    | i | j | k | l |\n\
///                    +---+---+---+---+\n\
///                    | m | n | o | p |\n\
///                    +---+---+---+---+\n\
///                    | q | r | s | t |\n\
///                    +---+---+---+---+\n\
///                    | u | v | w | x |\n\
///                    +---+---+---+---+\n\
///                    | y | z |   |   |\n\
///                    +---+---+---+---+")
/// ```
///
/// [`Table`]: crate::Table
#[derive(Debug, Clone, Copy)]
pub struct Split {
    direction: Direction,
    behavior: Behavior,
    display: Display,
    index: usize,
}

impl Split {
    /// Returns a new [`Table`] split on the column at the provided index.
    ///
    /// The column found at that index becomes the new right-most column in the returned table.
    /// Columns found beyond the index are redistributed into the table based on other defined
    /// parameters.
    ///
    /// ```rust,no_run
    /// # use tabled::settings::split::Split;
    /// Split::column(4);
    /// ```
    ///
    /// [`Table`]: crate::Table
    pub fn column(index: usize) -> Self {
        Split {
            direction: Direction::Column,
            behavior: Behavior::Zip,
            display: Display::Clean,
            index,
        }
    }

    /// Returns a new [`Table`] split on the row at the provided index.
    ///
    /// The row found at that index becomes the new bottom row in the returned table.
    /// Rows found beyond the index are redistributed into the table based on other defined
    /// parameters.
    ///
    /// ```rust,no_run
    /// # use tabled::settings::split::Split;
    /// Split::row(4);
    /// ```
    ///
    /// [`Table`]: crate::Table
    pub fn row(index: usize) -> Self {
        Split {
            direction: Direction::Row,
            behavior: Behavior::Zip,
            display: Display::Clean,
            index,
        }
    }

    /// Returns a split [`Table`] with the redistributed cells pushed to the back of the new shape.
    ///
    /// ```text
    ///                                                 +---+---+
    ///                                                 | a | b |
    ///                                                 +---+---+
    /// +---+---+---+---+---+                           | f | g |
    /// | a | b | c | d | e | Split::column(2).concat() +---+---+
    /// +---+---+---+---+---+           =>              | c | d |
    /// | f | g | h | i | j |                           +---+---+
    /// +---+---+---+---+---+                           | h | i |
    ///                                                 +---+---+
    ///                                                 | e |   |
    ///                                                 +---+---+
    ///                                                 | j |   |
    ///                                                 +---+---+
    /// ```
    ///
    /// [`Table`]: crate::Table
    pub fn concat(self) -> Self {
        Self {
            behavior: Behavior::Concat,
            ..self
        }
    }

    /// Returns a split [`Table`] with the redistributed cells inserted behind
    /// the first correlating column/row one after another.
    ///
    /// ```text
    ///                                              +---+---+
    ///                                              | a | b |
    ///                                              +---+---+
    /// +---+---+---+---+---+                        | c | d |
    /// | a | b | c | d | e | Split::column(2).zip() +---+---+
    /// +---+---+---+---+---+           =>           | e |   |
    /// | f | g | h | i | j |                        +---+---+
    /// +---+---+---+---+---+                        | f | g |
    ///                                              +---+---+
    ///                                              | h | i |
    ///                                              +---+---+
    ///                                              | j |   |
    ///                                              +---+---+
    /// ```
    ///
    /// [`Table`]: crate::Table
    pub fn zip(self) -> Self {
        Self {
            behavior: Behavior::Zip,
            ..self
        }
    }

    /// Returns a split [`Table`] with the empty columns/rows filtered out.
    ///
    /// ```text
    ///                                                
    ///                                                
    ///                                                +---+---+---+
    /// +---+---+---+---+---+                          | a | b | c |
    /// | a | b | c | d | e | Split::column(3).clean() +---+---+---+
    /// +---+---+---+---+---+           =>             | d | e |   |
    /// | f | g | h |   |   |                          +---+---+---+
    /// +---+---+---+---+---+                          | f | g | h |
    ///               ^   ^                            +---+---+---+
    ///               these cells are filtered
    ///               from the resulting table
    /// ```
    ///
    /// ## Notes
    ///
    /// This is apart of the default configuration for Split.
    ///
    /// See [`retain`] for an alternative display option.
    ///
    /// [`Table`]: crate::Table
    /// [`retain`]: crate::settings::split::Split::retain
    pub fn clean(self) -> Self {
        Self {
            display: Display::Clean,
            ..self
        }
    }

    /// Returns a split [`Table`] with all cells retained.
    ///
    /// ```text
    ///                                                 +---+---+---+
    ///                                                 | a | b | c |
    ///                                                 +---+---+---+
    /// +---+---+---+---+---+                           | d | e |   |
    /// | a | b | c | d | e | Split::column(3).retain() +---+---+---+
    /// +---+---+---+---+---+           =>              | f | g | h |
    /// | f | g | h |   |   |                           +---+---+---+
    /// +---+---+---+---+---+             |-----------> |   |   |   |
    ///               ^   ^               |             +---+---+---+
    ///               |___|_____cells are kept!
    /// ```
    ///
    /// ## Notes
    ///
    /// See [`clean`] for an alternative display option.
    ///
    /// [`Table`]: crate::Table
    /// [`clean`]: crate::settings::split::Split::clean
    pub fn retain(self) -> Self {
        Self {
            display: Display::Retain,
            ..self
        }
    }
}

impl<R, D, C> TableOption<R, C, D> for Split
where
    R: Records + ExactRecords + Resizable + PeekableRecords,
{
    fn change(self, records: &mut R, _: &mut C, _: &mut D) {
        // variables
        let Split {
            direction,
            behavior,
            display,
            index: section_length,
        } = self;
        let mut filtered_sections = 0;

        // early return check
        if records.count_columns() == 0 || records.count_rows() == 0 || section_length == 0 {
            return;
        }

        // computed variables
        let (primary_length, secondary_length) = compute_length_arrangement(records, direction);
        let sections_per_direction = ceil_div(primary_length, section_length);
        let (outer_range, inner_range) =
            compute_range_order(secondary_length, sections_per_direction, behavior);

        // work
        for outer_index in outer_range {
            let from_secondary_index = outer_index * sections_per_direction - filtered_sections;
            for inner_index in inner_range.clone() {
                let (section_index, from_secondary_index, to_secondary_index) =
                    compute_range_variables(
                        outer_index,
                        inner_index,
                        secondary_length,
                        from_secondary_index,
                        sections_per_direction,
                        filtered_sections,
                        behavior,
                    );

                match (direction, behavior) {
                    (Direction::Column, Behavior::Concat) => records.push_row(),
                    (Direction::Column, Behavior::Zip) => records.insert_row(to_secondary_index),
                    (Direction::Row, Behavior::Concat) => records.push_column(),
                    (Direction::Row, Behavior::Zip) => records.insert_column(to_secondary_index),
                }

                let section_is_empty = copy_section(
                    records,
                    section_length,
                    section_index,
                    primary_length,
                    from_secondary_index,
                    to_secondary_index,
                    direction,
                );

                if section_is_empty && display == Display::Clean {
                    delete(records, to_secondary_index, direction);
                    filtered_sections += 1;
                }
            }
        }

        cleanup(records, section_length, primary_length, direction);
    }
}

/// Determine which direction should be considered the primary, and which the secondary based on direction
fn compute_length_arrangement<R>(records: &mut R, direction: Direction) -> (usize, usize)
where
    R: Records + ExactRecords,
{
    match direction {
        Direction::Column => (records.count_columns(), records.count_rows()),
        Direction::Row => (records.count_rows(), records.count_columns()),
    }
}

/// reduce the table size to the length of the index in the specified direction
fn cleanup<R>(records: &mut R, section_length: usize, primary_length: usize, direction: Direction)
where
    R: Resizable,
{
    for segment in (section_length..primary_length).rev() {
        match direction {
            Direction::Column => records.remove_column(segment),
            Direction::Row => records.remove_row(segment),
        }
    }
}

/// Delete target index row or column
fn delete<R>(records: &mut R, target_index: usize, direction: Direction)
where
    R: Resizable,
{
    match direction {
        Direction::Column => records.remove_row(target_index),
        Direction::Row => records.remove_column(target_index),
    }
}

/// copy cells to new location
///
/// returns if the copied section was entirely blank
fn copy_section<R>(
    records: &mut R,
    section_length: usize,
    section_index: usize,
    primary_length: usize,
    from_secondary_index: usize,
    to_secondary_index: usize,
    direction: Direction,
) -> bool
where
    R: ExactRecords + Resizable + PeekableRecords,
{
    let mut section_is_empty = true;
    for to_primary_index in 0..section_length {
        let from_primary_index = to_primary_index + section_index * section_length;

        if from_primary_index < primary_length {
            let from_position =
                format_position(direction, from_primary_index, from_secondary_index);
            if !records.get_text(from_position).is_empty() {
                section_is_empty = false;
            }
            records.swap(
                from_position,
                format_position(direction, to_primary_index, to_secondary_index),
            );
        }
    }
    section_is_empty
}

/// determine section over direction or vice versa based on behavior
fn compute_range_order(
    direction_length: usize,
    sections_per_direction: usize,
    behavior: Behavior,
) -> (Range<usize>, Range<usize>) {
    match behavior {
        Behavior::Concat => (1..sections_per_direction, 0..direction_length),
        Behavior::Zip => (0..direction_length, 1..sections_per_direction),
    }
}

/// helper function for shimming both behaviors to work within a single nested loop
fn compute_range_variables(
    outer_index: usize,
    inner_index: usize,
    direction_length: usize,
    from_secondary_index: usize,
    sections_per_direction: usize,
    filtered_sections: usize,
    behavior: Behavior,
) -> (usize, usize, usize) {
    match behavior {
        Behavior::Concat => (
            outer_index,
            inner_index,
            inner_index + outer_index * direction_length - filtered_sections,
        ),
        Behavior::Zip => (
            inner_index,
            from_secondary_index,
            outer_index * sections_per_direction + inner_index - filtered_sections,
        ),
    }
}

/// utility for arguments of a position easily
fn format_position(direction: Direction, primary_index: usize, secondary_index: usize) -> Position {
    match direction {
        Direction::Column => (secondary_index, primary_index).into(),
        Direction::Row => (primary_index, secondary_index).into(),
    }
}

/// ceil division utility because the std lib ceil_div isn't stable yet
fn ceil_div(x: usize, y: usize) -> usize {
    debug_assert!(x != 0);
    1 + ((x - 1) / y)
}