[](https://crates.io/crates/uutils-term-grid)
[](https://deps.rs/repo/github/uutils/uutils-term-grid)
[](https://codecov.io/gh/uutils/uutils-term-grid)
# 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`](https://github.com/ogham/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:
```toml
[dependencies]
uutils_term_grid = "0.4"
```
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`][filling]: what to put in between two columns — either a number of
spaces, or a text string;
- [`direction`][direction]: specifies whether the cells should go along rows, or
columns:
- [`Direction::LeftToRight`][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`][TopToBottom] starts them in the top left and
moves _downwards_, going to the top of a new column after reaching the final
row.
- [`width`][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:
```rust
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:
```text
one two three four
five six seven eight
nine ten eleven twelve
```
[filling]: struct.GridOptions.html#structfield.filling
[direction]: struct.GridOptions.html#structfield.direction
[width]: struct.GridOptions.html#structfield.width
[LeftToRight]: enum.Direction.html#variant.LeftToRight
[TopToBottom]: enum.Direction.html#variant.TopToBottom
## Width of grid cells
This library calculates the width of strings as displayed in the terminal using
the [`textwrap`][textwrap] library (with the [`display_width`][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.
[textwrap]: https://docs.rs/textwrap/latest/textwrap/index.html
[display_width]: https://docs.rs/textwrap/latest/textwrap/core/fn.display_width.html