This library arranges textual data in a grid format suitable for fixed-width fonts, using an algorithm to minimise the amount of space needed.

This library is forked from the unmaintained rust-term-grid library. The core functionality has remained the same, with some additional bugfixes, performance improvements and a new API.

This crate works with cargo. Add the following to your Cargo.toml dependencies section:

[dependencies]
uutils_term_grid = "0.7"

The Minimum Supported Rust Version is 1.70.

To add data to a grid, first create a new [Grid] value with a list of strings and a set of options.

There are four options that can be configured in [GridOptions]. GridOptions implements Default, providing sensible defaults for all fields:

• filling: how to fill empty space between columns (defaults to Filling::Spaces(2)):
  • Filling::Spaces number of spaces between columns;
  • Filling::Text text string separator between columns;
  • Filling::Tabs special option which allows to set number of spaces between columns and set the size of \t character.
• direction: specifies whether the cells should go along rows, or columns (defaults to Direction::LeftToRight):
  • Direction::LeftToRight starts them in the top left and moves rightwards, going to the start of a new row after reaching the final column;
  • Direction::TopToBottom starts them in the top left and moves downwards, going to the top of a new column after reaching the final row.
• width: the width to fill the grid into (defaults to 80). Usually, this should be the actual width of the terminal.
• line_separator: the string to put at the end of each line/row in the grid (defaults to "\n").

In practice, creating a grid can be done as follows:

use term_grid::{Grid, GridOptions, Direction, Filling};

// Create a `Vec` of text to put in the grid
let cells = vec![
    "one", "two", "three", "four", "five", "six",
    "seven", "eight", "nine", "ten", "eleven", "twelve"
];

// Then create a `Grid` with those cells.
// The grid requires several options:
//  - The filling determines the string used as separator
//    between the columns.
//  - The direction specifies whether the layout should
//    be done row-wise or column-wise.
//  - The width is the maximum width that the grid might
//    have.
let grid = Grid::new(
    cells,
    GridOptions {
        filling: Filling::Spaces(1),
        direction: Direction::LeftToRight,
        width: 24,
        ..Default::default()
    }
);

// A `Grid` implements `Display` and can be printed directly.
println!("{grid}");

Produces the following tabular result:

one  two three  four
five six seven  eight
nine ten eleven twelve

By default, each row ends with a newline ("\n"). A custom line separator (such as "\0" or "\r\n") can be configured using line_separator:

use term_grid::{Grid, GridOptions, Direction, Filling};
let cells = vec!["one", "two", "three", "four"];
let options = GridOptions {
    filling: Filling::Spaces(1),
    direction: Direction::LeftToRight,
    width: 24,
    line_separator: "\0".into(),
    ..Default::default()
};
let grid = Grid::new(cells, options);

This library calculates the width of strings as displayed in the terminal using the ansi-width crate. This takes into account the width of characters and ignores ANSI codes.

The width calculation is currently not configurable. If you have a use-case for which this calculation is wrong, please open an issue.