Crate textwrap

textwrap provides functions for word wrapping and filling text.

Wrapping text can be very useful in commandline programs where you want to format dynamic output nicely so it looks good in a terminal. A quick example:

extern crate textwrap;
use textwrap::fill;

fn main() {
    let text = "textwrap: a small library for wrapping text.";
    println!("{}", fill(text, 18));
}

This will display the following output:

textwrap: a small
library for
wrapping text.

Displayed Width vs Byte Size

To word wrap text, one must know the width of each word so one can know when to break lines. This library measures the width of text using the displayed width, not the size in bytes.

This is important for non-ASCII text. ASCII characters such as a and ! are simple and take up one column each. This means that the displayed width is equal to the string length in bytes. However, non-ASCII characters and symbols take up more than one byte when UTF-8 encoded: é is 0xc3 0xa9 (two bytes) and ⚙ is 0xe2 0x9a 0x99 (three bytes) in UTF-8, respectively.

This is why we take care to use the displayed width instead of the byte count when computing line lengths. All functions in this library handle Unicode characters like this.

Structs

HyphenSplitter

Simple and default way to split words: splitting on existing hyphens only.

IntoWrapIter

An iterator over the lines of the input string which owns a Wrapper. An instance of IntoWrapIter is typically obtained through either wrap_iter or Wrapper::into_wrap_iter.

NoHyphenation

Use this as a Wrapper.splitter to avoid any kind of hyphenation:

WrapIter

An iterator over the lines of the input string which borrows a Wrapper. An instance of WrapIter is typically obtained through the Wrapper::wrap_iter method.

Wrapper

A Wrapper holds settings for wrapping and filling text. Use it when the convenience wrap_iter, wrap and fill functions are not flexible enough.

Traits

WordSplitter

An interface for splitting words.

Functions

dedent

Removes common leading whitespace from each line.

fill

Fill a line of text at width characters. Strings are wrapped based on their displayed width, not their size in bytes.

indent

Add prefix to each non-empty line.

wrap

Wrap a line of text at width characters. Strings are wrapped based on their displayed width, not their size in bytes.

wrap_iter

Lazily wrap a line of text at width characters. Strings are wrapped based on their displayed width, not their size in bytes.