Crate pad [−] [src]

This is a library for padding strings at runtime.

The routines in std::fmt only work with formatting strings provided at compile-time, making them unsuitable for padding to a custom or user-defined value. Rather than re-implement all of std::fmt, padding is probably the most common use case, which is written in a more runtime-friendly fashion here.

It provides four helper functions for the most common use cases, and one main function (pad) to cover the other cases.

String length is determined with the width function, without assuming CJK.

Examples

You can pad a string to have a minimum width with the pad_to_width method:

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.

Alignment

By default, strings are left-aligned: any extra characters are added on the right. To change this, pass in an Alignment value:

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:

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.

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:

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.)

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.

Enums

Alignment

An alignment tells the padder where to put the spaces.

Traits

PadStr

Functions to do with string padding.