Repository files navigation

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

This library is forked from the unmaintainedrust-term-grid library. The corefunctionality has remained the same, with some additional bugfixes, performanceimprovements and a new API.

This crate works withcargo. Add the following to yourCargo.tomldependencies 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 stringsand a set of options.

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

• filling: how to fill empty space between columns:
  • 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, orcolumns:
  • Direction::LeftToRight starts them in the top left andmovesrightwards, going to the start of a new row after reaching the finalcolumn;
  • Direction::TopToBottom starts them in the top left andmovesdownwards, going to the top of a new column after reaching the finalrow.
• width: the width to fill the grid into. Usually, this should be thewidth 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 gridlet 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  fourfive six seven  eightnine ten eleven twelve

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

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