Lib.rs

🔎 Overview

Pad and format virtually any generic slice or vector efficiently with minimal memory overhead. This crate has guaranteed performance improvements over the standard library format! macro. Clone this repository and run cargo bench to see benchmark comparisons between this implementation and the standard library.

The library defines a core trait called Source which enables efficient padding on the type. It is currently implemented on three main types of datastructures: the string slice &str, the generic slice &[T], and also the generic vector Vec<T>. Note that the type T has to adhere to the trait bound T: From<Symbol>, where Symbol is the Enum representing the available characters/symbols to pad and format with. If you want to extend the padding capabilities of the Source trait with your own type T, then you need to also implement the From<Symbol> trait for your type T. See the implementations for examples on how to do this, link.

📦 Installation

The easiest way to include padder in your own crate is by using the Cargo package manager.

$ cargo add padder

Alternatively, you can build from source by cloning this repo and compiling using Cargo and then linking the library to your project.

$ git clone https://github.com/firelink-data/padder.git
$ cd padder
$ cargo build --release

🚀 Examples

Adding padder to your crate dependecy will bring the Source trait into scope and allow padding.

You can for example pad string slices very easily in the following way:

let padded: String = "cool".pad(10, Alignment::Center, Symbol::Zero);

which would produce the padded String 000cool000. You can also pad to an already allocated buffer, granting you full control of any heap allocations, like below:

let width: usize = 8;
let mut output: Vec<u8> = Vec::with_capacity(width);
let original = vec![13u8, 9, 128, 81];
original.pad_and_push_to_buffer(width, Alignment::Right, Symbol::Whitespace, output);

There also exists two wrapper methods simply called pad and pad_and_push_to_buffer which allows padding on any type as long as it implements the Source trait. You can for example use these functions like below:

// pad
let original: &str = "hej";
let width: usize = 9;
let output: String = pad(original, width, Alignment::Left, Symbol::Hyphen);

// pad_and_push_to_buffer
let buffer = String::with_capacity(11);
pad_and_push_to_buffer("testcool", 11, Alignment::Right, Symbol::Whitespace);

which would produce the strings hej------ and testcool.

📋 License

All code is to be held under a general MIT license, please see LICENSE for specific information.