Merge pull request #27 from tertsdiepraam/api-changes

tertsdiepraam · web-flow · commit 9bb0ae8eccd6 · 2023-11-07T16:26:48.000+01:00
API changes
diff --git a/Cargo.toml b/Cargo.toml
@@ -15,4 +15,4 @@ rust-version = "1.70"
 name = "term_grid"
 
 [dependencies]
-unicode-width = "0.1.11"
+textwrap = { version = "0.16.0", default-features = false, features = ["unicode-width"] }
diff --git a/README.md b/README.md
@@ -2,20 +2,24 @@
 [![dependency status](https://deps.rs/repo/github/uutils/uutils-term-grid/status.svg)](https://deps.rs/repo/github/uutils/uutils-term-grid)
 [![CodeCov](https://codecov.io/gh/uutils/uutils-term-grid/branch/master/graph/badge.svg)](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 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 [`rust-term-grid`](https://github.com/ogham/rust-term-grid) library.
+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:
+This crate works with `cargo`. Add the following to your `Cargo.toml`
+dependencies section:
 
 ```toml
 [dependencies]
@@ -24,70 +28,81 @@ uutils_term_grid = "0.3"
 
 The Minimum Supported Rust Version is 1.70.
 
+## Creating a grid
 
-## Usage
+To add data to a grid, first create a new [`Grid`] value with a list of strings
+and a set of options.
 
-This library arranges textual data in a grid format suitable for fixed-width fonts, using an algorithm to minimise the amount of space needed.
-For example:
+There are three options that must be specified in the [`GridOptions`] value that
+dictate how the grid is formatted:
 
-```rust
-use term_grid::{Grid, GridOptions, Direction, Filling, Cell};
+- [`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.
 
-let mut grid = Grid::new(GridOptions {
-    filling:     Filling::Spaces(1),
-    direction:   Direction::LeftToRight,
-});
+In practice, creating a grid can be done as follows:
 
-for s in &["one", "two", "three", "four", "five", "six", "seven",
-           "eight", "nine", "ten", "eleven", "twelve"]
-{
-    grid.add(Cell::from(*s));
-}
-
-println!("{}", grid.fit_into_width(24).unwrap());
+```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
 
-## Creating a grid
-
-To add data to a grid, first create a new `Grid` value, and then add cells to them with the `add` method.
-
-There are two 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`, which 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.
-
-
-## Displaying a grid
-
-When display a grid, you can either specify the number of columns in advance, or try to find the maximum number of columns that can fit in an area of a given width.
-
-Splitting a series of cells into columns - or, in other words, starting a new row every *n* cells - is achieved with the `fit_into_columns` method on a `Grid` value.
-It takes as its argument the number of columns.
-
-Trying to fit as much data onto one screen as possible is the main use case for specifying a maximum width instead.
-This is achieved with the `fit_into_width` method.
-It takes the maximum allowed width, including separators, as its argument.
-However, it returns an *optional* `Display` value, depending on whether any of the cells actually had a width greater than the maximum width!
-If this is the case, your best bet is to just output the cells with one per line.
-
-
-## Cells and data
+## Width of grid cells
 
-Grids do not take `String`s or `&str`s - they take `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.
 
-A **Cell** is a struct containing an individual cell’s contents, as a string, and its pre-computed length, which gets used when calculating a grid’s final dimensions.
-Usually, you want the *Unicode width* of the string to be used for this, so you can turn a `String` into a `Cell` with the `.into()` method.
+The width calculation is currently not configurable. If you have a use-case for
+which this calculation is wrong, please open an issue.
 
-However, you may also want to supply your own width: when you already know the width in advance, or when you want to change the measurement, such as skipping over terminal control characters.
-For cases like these, the fields on the `Cell` values are public, meaning you can construct your own instances as necessary.
+[textwrap]: https://docs.rs/textwrap/latest/textwrap/index.html
+[display_width]: https://docs.rs/textwrap/latest/textwrap/core/fn.display_width.html
diff --git a/examples/basic.rs b/examples/basic.rs
@@ -1,5 +1,7 @@
-extern crate term_grid;
-use term_grid::{Cell, Direction, Filling, Grid, GridOptions};
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use term_grid::{Direction, Filling, Grid, GridOptions};
 
 // This produces:
 //
@@ -12,19 +14,16 @@ use term_grid::{Cell, Direction, Filling, Grid, GridOptions};
 // 64 | 8192 | 1048576 | 134217728 | 17179869184 | 2199023255552 |
 
 fn main() {
-    let mut grid = Grid::new(GridOptions {
-        direction: Direction::TopToBottom,
-        filling: Filling::Text(" | ".into()),
-    });
+    let cells: Vec<_> = (0..48).map(|i| 2_isize.pow(i).to_string()).collect();
 
-    for i in 0..48 {
-        let cell = Cell::from(2_isize.pow(i).to_string());
-        grid.add(cell)
-    }
+    let grid = Grid::new(
+        cells,
+        GridOptions {
+            direction: Direction::TopToBottom,
+            filling: Filling::Text(" | ".into()),
+            width: 80,
+        },
+    );
 
-    if let Some(grid_display) = grid.fit_into_width(80) {
-        println!("{}", grid_display);
-    } else {
-        println!("Couldn't fit grid into 80 columns!");
-    }
+    println!("{}", grid);
 }
diff --git a/examples/big.rs b/examples/big.rs
@@ -1,26 +1,26 @@
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
-extern crate term_grid;
-use term_grid::{Cell, Direction, Filling, Grid, GridOptions};
+use term_grid::{Direction, Filling, Grid, GridOptions};
 
 fn main() {
-    let mut grid = Grid::new(GridOptions {
-        direction: Direction::TopToBottom,
-        filling: Filling::Text(" | ".into()),
-    });
-
     let mut n: u64 = 1234;
     for _ in 0..50 {
+        let mut cells = Vec::new();
         for _ in 0..10000 {
-            grid.add(Cell::from(n.to_string()));
+            cells.push(n.to_string());
             n = n.overflowing_pow(2).0 % 100000000;
         }
 
-        if let Some(grid_display) = grid.fit_into_width(80) {
-            println!("{}", grid_display);
-        } else {
-            println!("Couldn't fit grid into 80 columns!");
-        }
+        let grid = Grid::new(
+            cells,
+            GridOptions {
+                direction: Direction::TopToBottom,
+                filling: Filling::Text(" | ".into()),
+                width: 80,
+            },
+        );
+
+        println!("{grid}");
     }
 }
diff --git a/src/lib.rs b/src/lib.rs
diff --git a/tests/test.rs b/tests/test.rs
