1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
# 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.
|
