README.md

uutils-term-grid

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.

---

Installation

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

[dependencies]
uutils_term_grid = "0.6"

The Minimum Supported Rust Version is 1.70.

Creating a grid

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

There are three options that must be specified in the [GridOptions] value that dictate how the grid is formatted:

• filling: what to put in between two columns — either a number of spaces, or a text string;
• direction: specifies whether the cells should go along rows, or columns:
  • 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. Usually, this should be the width of the terminal.

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

// 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

Width of grid cells

This library calculates the width of strings as displayed in the terminal using the textwrap library (with the display_width function). 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.