Struct Printer

Source

pub struct Printer { /* private fields */ }

Expand description

§Screen Printer

Screen Printer is a rust crate that will allow you to build and print arrays of data into a grid format.

The purpose of this crate is to make it easier to print rectangular blocks of text to the terminal. Including features like:

DynamicPrint, which only prints any characters that changed from any previously printed grid*.
PrintingPosition, which allows you to print your string to different places on the terminal, such as the center.

* If the grid changes in size or position it is reprinted in its entirety.

§Examples

§Using the dynamic print method to print a grid

The core part of this crate is the dynamic_print method. This will take a rectangular grid of characters, and print only the parts of the grid that have changed since the last print.

use screen_printer::printer::*;

const WIDTH: usize = 3;
const HEIGHT: usize = 3;

fn main() {
  print!("\u{1b}[2J"); // Clear all text on the terminal
  // The default printing position is the bottom left of the terminal
  let mut printer = Printer::new_with_printing_position(PrintingPosition::default());

  // Create the first grid to be printed.
  let grid_1 = "abc\n123\nxyz".to_string();
  // print the first grid.
  printer.dynamic_print(grid_1).unwrap();

  // Wait before printing the second grid.
  std::thread::sleep(std::time::Duration::from_millis(500));

  // Create the second grid to be printed.
  let grid_2 = "abc\n789\nxyz".to_string();
  // Print the second grid.
  // This will only end up printing the difference between the two grids/
  printer.dynamic_print(grid_2).unwrap();
}

This will result in

abc
123
xyz

Into

abc
789 < only line that was actually printed
xyz

§Printing Position

Another feature shown in the above example, the PrintingPosition.

This will print the grid in any of the 9 defined positions on the terminal. These are split by the X and Y axes:

Left/Top,
Middle, and;
Right/Bottom.

Implementations§

Source §

impl Printer

Source

pub fn new() -> Self

Creates a new printer for the dynamic_print() method.

Uses the default PrintingPosition

Source

pub fn new_with_printing_position(printing_position: PrintingPosition) -> Self

Creates a new printer for the dynamic_print() method with the given printing position.

PrintingPositons tell the printer where to print any grids passed into it. Refer to PrintingPosition for more information;

Source

pub fn replace_printing_position(&mut self, printing_position: PrintingPosition)

Source

pub fn replace_x_printing_position( &mut self, new_x_printing_position: XPrintingPosition, ) -> Result<(), PrintingError>

§Errors

There is no defined printing position

Source

pub fn replace_y_printing_position( &mut self, new_y_printing_position: YPrintingPosition, ) -> Result<(), PrintingError>

§Errors

There is no defined printing position

Source

pub fn get_current_printing_position(&self) -> &PrintingPosition

Returns a reference to the currently stored printing position.

Source

pub fn create_grid_from_single_character( character: char, width: usize, height: usize, ) -> String

Creates a grid of the given size with the given character.

§Example

use screen_printer::printer::*;

let character = 'a';
let expected_grid = "aaa\naaa\naaa";

let grid = Printer::create_grid_from_single_character(character, 3, 3);

assert_eq!(expected_grid, grid);

Source

pub fn create_grid_from_full_character_list<T>( characters: &Vec<T>, width: usize, height: usize, ) -> Result<String, PrintingError>
where T: Display,

Creates a grid of the given size with the given list of characters

§Example

use screen_printer::printer::*;

let characters = vec!["a", "b", "c", "d", "e", "f", "g", "h", "i"];
let expected_grid = "abc\ndef\nghi";

let grid = Printer::create_grid_from_full_character_list(&characters, 3, 3).unwrap();

assert_eq!(expected_grid, grid);

§Errors

When the amount of characters passed in doesn’t fit the expected grid dimensions.

Source

pub fn print_over_previous_grid(grid: String, height: usize)

Moves the cursor up by the given height and prints the given grid.

This is for printing over the previously printed grid. It’s recommended to add some whitespace before your first print so the grid doesn’t print into anything that was printed before this method was called.

§Example

use screen_printer::printer::*;

let height = 10;
let width = 10;
let grid = Printer::create_grid_from_single_character('a', width, height);

print!("{}", "\n".repeat(height + 5)); // add some space for the grid
Printer::print_over_previous_grid(grid, height);

Source

pub fn get_rectangular_dimensions( rectangle_shape: &str, ) -> Result<(usize, usize), PrintingError>

Returns the dimensions of the passed in string. An error is returned if the string is non-rectangular

§Errors

The passed in string is non-rectangular.

Source

pub fn is_rectangular(rectangle_shape: &str) -> bool

Returns true if the passed in string is rectangular in shape.

§Examples

Valid rectangle: "xxxxx\nxxxxx

Invalid rectangle: "xxxxx\nxxx

Source

pub fn get_terminal_dimensions() -> Result<(usize, usize), PrintingError>

Returns the current dimensions of the terminal.

§Errors

Whenever termion::terminal_size can fail. They don’t document it themselves.

Source

pub fn reset(&mut self)

Resets all data for the printer.

Source

pub fn reset_and_retain_printing_position(&mut self)

Resets all data for the printer except for the current position.

Source

pub fn reset_with_position(&mut self, printing_position: PrintingPosition)

Resets all data for the printer and assigns the given printing position.

Source

pub fn pad_rows_for_rectangle(grid: &mut String)

Adds whitespace to every row in the grid to match the length of the longest.

This is for turning non-rectangular strings into rectangles for being printed with dynamic_print

§Examples

use screen_printer::printer::*;

let mut grid = "xxx\nxx\nx".to_string();

Printer::pad_rows_for_rectangle(&mut grid);

assert!(Printer::is_rectangular(&grid));
assert_eq!(&grid, "xxx\nxx \nx  ");