Need help with textwrap?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

mgeisler
212 Stars 24 Forks MIT License 834 Commits 22 Opened issues

Description

An efficient and powerful Rust library for word wrapping text.

Services available

!
?

Need anything else?

Contributors list

Textwrap

Textwrap is a library for wrapping and indenting text. It is most often used by command-line programs to format dynamic output nicely so it looks good in a terminal. You can also use Textwrap to wrap text set in a proportional font—such as text used to generate PDF files, or drawn on a HTML5 canvas using WebAssembly.

Usage

To use the textwrap crate, add this to your

Cargo.toml
file:
toml
[dependencies]
textwrap = "0.14"

By default, this enables word wrapping with support for Unicode strings. Extra features can be enabled with Cargo features—and the Unicode support can be disabled if needed. This allows you slim down the library and so you will only pay for the features you actually use. Please see the Cargo Features in the crate documentation for a full list of the available features.

Documentation

API documentation

Getting Started

Word wrapping is easy using the

fill
function:
fn main() {
    let text = "textwrap: an efficient and powerful library for wrapping text.";
    println!("{}", textwrap::fill(text, 28));
}

The output is wrapped within 28 columns:

textwrap: an efficient
and powerful library for
wrapping text.

Sharp-eyed readers will notice that the first line is 22 columns wide. So why is the word “and” put in the second line when there is space for it in the first line?

The explanation is that textwrap does not just wrap text one line at a time. Instead, it uses an optimal-fit algorithm which looks ahead and chooses line breaks which minimize the gaps left at ends of lines.

Without look-ahead, the first line would be longer and the text would look like this:

textwrap: an efficient and
powerful library for
wrapping text.

The second line is now shorter and the text is more ragged. The kind of wrapping can be configured via

Options::wrap_algorithm
.

If you enable the

hyphenation
Cargo feature, you get support for automatic hyphenation for about 70 languages via high-quality TeX hyphenation patterns.

Your program must load the hyphenation pattern and configure

Options::word_splitter
to use it:
use hyphenation::{Language, Load, Standard};
use textwrap::{fill, Options};

fn main() { let hyphenator = Standard::from_embedded(Language::EnglishUS).unwrap(); let options = Options::new(28).word_splitter(hyphenator); let text = "textwrap: an efficient and powerful library for wrapping text."; println!("{}", fill(text, &options)); }

The output now looks like this:

textwrap: an efficient and
powerful library for wrap-
ping text.

The US-English hyphenation patterns are embedded when you enable the

hyphenation
feature. They are licensed under a permissive license and take up about 88 KB in your binary. If you need hyphenation for other languages, you need to download a precompiled
.bincode
file
and load it yourself. Please see the
hyphenation
documentation
for details.

Wrapping Strings at Compile Time

If your strings are known at compile time, please take a look at the procedural macros from the

textwrap-macros
crate.

Examples

The library comes with a collection of small example programs that shows various features.

If you want to see Textwrap in action right away, then take a look at

examples/wasm/
, which shows how to wrap sans-serif, serif, and monospace text. It uses WebAssembly and is automatically deployed to https://mgeisler.github.io/textwrap/.

For the command-line examples, you’re invited to clone the repository and try them out for yourself! Of special note is

examples/interactive.rs
. This is a demo program which demonstrates most of the available features: you can enter text and adjust the width at which it is wrapped interactively. You can also adjust the

Options
used to see the effect of different
WordSplitter
s and wrap algorithms.

Run the demo with

$ cargo run --example interactive

The demo needs a Linux terminal to function.

Release History

Please see the CHANGELOG file for details on the changes made in each release.

License

Textwrap can be distributed according to the MIT license. Contributions will be accepted under the same license.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.