Struct Split

Source

pub struct Split { /* private fields */ }

Expand description

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.

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));

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ 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.

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());

                                                +---+---+
                                                | 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.

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

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ 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

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\
                   +---+---+---+---+")

Implementations§

Source §

impl Split

Source

pub fn column(index: usize) -> Self

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.

Split::column(4);

Source

pub fn row(index: usize) -> Self

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.

Split::row(4);

Source

pub fn concat(self) -> Self

Returns a split Table with the redistributed cells pushed to the back of the new shape.

                                                +---+---+
                                                | a | b |
                                                +---+---+
+---+---+---+---+---+                           | f | g |
| a | b | c | d | e | Split::column(2).concat() +---+---+
+---+---+---+---+---+           =>              | c | d |
| f | g | h | i | j |                           +---+---+
+---+---+---+---+---+                           | h | i |
                                                +---+---+
                                                | e |   |
                                                +---+---+
                                                | j |   |
                                                +---+---+

Source

pub fn zip(self) -> Self

Returns a split Table with the redistributed cells inserted behind the first correlating column/row one after another.

                                             +---+---+
                                             | a | b |
                                             +---+---+
+---+---+---+---+---+                        | c | d |
| a | b | c | d | e | Split::column(2).zip() +---+---+
+---+---+---+---+---+           =>           | e |   |
| f | g | h | i | j |                        +---+---+
+---+---+---+---+---+                        | f | g |
                                             +---+---+
                                             | h | i |
                                             +---+---+
                                             | j |   |
                                             +---+---+

Source

pub fn clean(self) -> Self

Returns a split Table with the empty columns/rows filtered out.

                                                
                                                
                                               +---+---+---+
+---+---+---+---+---+                          | 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.

Source

pub fn retain(self) -> Self

Returns a split Table with all cells retained.

                                                +---+---+---+
                                                | a | b | c |
                                                +---+---+---+
+---+---+---+---+---+                           | d | e |   |
| a | b | c | d | e | Split::column(3).retain() +---+---+---+
+---+---+---+---+---+           =>              | f | g | h |
| f | g | h |   |   |                           +---+---+---+
+---+---+---+---+---+             |-----------> |   |   |   |
              ^   ^               |             +---+---+---+
              |___|_____cells are kept!