# rust-pad [](https://crates.io/crates/pad) [](https://travis-ci.org/ogham/rust-pad)
This is a library for padding strings at runtime.
It provides four helper functions for the most common use cases, and one
main function to cover the other cases.
### [View the Rustdoc](https://docs.rs/pad)
# Installation
This crate works with [Cargo](http://crates.io). Add the following to your `Cargo.toml` dependencies section:
```toml
[dependencies]
pad = "0.1"
```
# Padding in the stdlib
**You do not need this crate for simple padding!**
It’s possible to pad strings using the Rust standard library.
For example, to pad a number with zeroes:
```rust
// Padding using std::fmt
assert_eq!("0000012345", format!("{:0>10}", 12345));
```
You can even use a variable for the padding width:
```rust
// Padding using std::fmt
assert_eq!("hello ", format!("{:width$}", "hello", width=12));
```
The [Rust documentation for `std::fmt`](https://doc.rust-lang.org/std/fmt/)
contains more examples. The rest of the examples will use the `pad` crate.
# Usage
You can pad a string to have a minimum width with the `pad_to_width`
method:
```rust
use pad::PadStr;
println!("{}", "Hi there!".pad_to_width(16));
```
This will print out “Hi there!” followed by seven spaces, which is the
number of spaces necessary to bring it up to a total of sixteen characters
wide.
String length is determined with the
[unicode_width](https://unicode-rs.github.io/unicode-width/unicode_width/index.html)
crate, without assuming CJK.
## Alignment
By default, strings are left-aligned: any extra characters are added on
the right. To change this, pass in an `Alignment` value:
```rust
use pad::{PadStr, Alignment};
let s = "I'm over here".pad_to_width_with_alignment(20, Alignment::Right);
```
There are four of these in total:
- **Left**, which puts the text on the left and spaces on the right;
- **Right**, which puts the text on the right and spaces on the left;
- **Middle**, which centres the text evenly, putting it slightly to the left if it can’t be exactly centered;
- **MiddleRight**, as above, but to the right.
## Characters
Another thing that’s set by default is the character that’s used to pad
the strings — by default, it’s space, but you can change it:
```rust
use pad::PadStr;
let s = "Example".pad_to_width_with_char(10, '_');
```
## Truncation
Finally, you can override what happens when a value exceeds the width you
give. By default, the width parameter indicates a *minimum width*: any
string less will be padded, but any string greater will still be returned
in its entirety.
You can instead tell it to pad with a maximum value, which will truncate
the input when a string longer than the width is passed in.
```rust
use pad::PadStr;
let short = "short".with_exact_width(10); // "short "
let long = "this string is long".with_exact_width(10); // "this strin"
```
# A Full Example
All of the above functions delegate to the `pad` function, which you can
use in special cases. Here, in order to **right**-pad a number with
**zeroes**, pass in all the arguments:
```rust
use pad::{PadStr, Alignment};
let s = "12345".pad(10, '0', Alignment::Right, true);
```
(The `true` at the end could just as easily be `false`. It’s whether to
truncate or not.)
# A Note on Debugging
One very last point: the width function takes a `usize`, rather than a
signed number type. This means that if you try to pass in a negative size,
it’ll wrap around to a positive size, and produce a massive string and
possibly crash your program. So if your padding calls are failing for some
reason, this is probably why.