[−][src]Crate 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 (pad
) to cover the other cases.
String length is determined with the width function, without assuming CJK.
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:
// Padding using std::fmt assert_eq!("0000012345", format!("{:0>10}", 12345));
You can even use a variable for the padding width:
// Padding using std::fmt assert_eq!("hello ", format!("{:width$}", "hello", width=12));
The Rust documentation for std::fmt
contains more examples. The rest of the examples will use the pad
crate.
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 governs 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. |