pub struct Wrapper<'a, S: WordSplitter> {
    pub width: usize,
    pub initial_indent: &'a str,
    pub subsequent_indent: &'a str,
    pub break_words: bool,
    pub splitter: S,
}
Expand description

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

The algorithm used by the WrapIter iterator (returned from the wrap_iter method) works by doing successive partial scans over words in the input string (where each single scan yields a single line) so that the overall time and memory complexity is O(n) where n is the length of the input string.

Fields

width: usize

The width in columns at which the text will be wrapped.

initial_indent: &'a str

Indentation used for the first line of output.

subsequent_indent: &'a str

Indentation used for subsequent lines of output.

break_words: bool

Allow long words to be broken if they cannot fit on a line. When set to false, some lines may be longer than self.width.

splitter: S

The method for splitting words. If the hyphenation feature is enabled, you can use a hyphenation::Standard dictionary here to get language-aware hyphenation.

Implementations

Create a new Wrapper for wrapping at the specified width. By default, we allow words longer than width to be broken. A HyphenSplitter will be used by default for splitting words. See the WordSplitter trait for other options.

Use the given WordSplitter to create a new Wrapper for wrapping at the specified width. By default, we allow words longer than width to be broken.

Change self.initial_indent. The initial indentation is used on the very first line of output.

Examples

Classic paragraph indentation can be achieved by specifying an initial indentation and wrapping each paragraph by itself:

use textwrap::Wrapper;

let wrapper = Wrapper::new(15).initial_indent("    ");

Change self.subsequent_indent. The subsequent indentation is used on lines following the first line of output.

Examples

Combining initial and subsequent indentation lets you format a single paragraph as a bullet list:

use textwrap::Wrapper;

let wrapper = Wrapper::new(15)
    .initial_indent("* ")
    .subsequent_indent("  ");

Change self.break_words. This controls if words longer than self.width can be broken, or if they will be left sticking out into the right margin.

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

The result is a string with newlines between each line. Use the wrap method if you need access to the individual lines.

Complexities

This method simply joins the lines produced by wrap_iter. As such, it inherits the O(n) time and memory complexity where n is the input string length.

Examples
use textwrap::Wrapper;

let wrapper = Wrapper::new(15);
assert_eq!(wrapper.fill("Memory safety without garbage collection."),
           "Memory safety\nwithout garbage\ncollection.");

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

Complexities

This method simply collects the lines produced by wrap_iter. As such, it inherits the O(n) overall time and memory complexity where n is the input string length.

Examples
use textwrap::Wrapper;

let wrap15 = Wrapper::new(15);
assert_eq!(wrap15.wrap("Concurrency without data races."),
           vec!["Concurrency",
                "without data",
                "races."]);

let wrap20 = Wrapper::new(20);
assert_eq!(wrap20.wrap("Concurrency without data races."),
           vec!["Concurrency without",
                "data races."]);

Notice that newlines in the input are preserved. This means that they force a line break, regardless of how long the current line is:

use textwrap::Wrapper;

let wrapper = Wrapper::new(40);
assert_eq!(wrapper.wrap("First line.\nSecond line."),
           vec!["First line.", "Second line."]);

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

The WordSplitter stored in self.splitter is used whenever when a word is too large to fit on the current line. By changing the field, different hyphenation strategies can be implemented.

Complexities

This method returns a WrapIter iterator which borrows this Wrapper. The algorithm used has a linear complexity, so getting the next line from the iterator will take O(w) time, where w is the wrapping width. Fully processing the iterator will take O(n) time for an input string of length n.

When no indentation is used, each line returned is a slice of the input string and the memory overhead is thus constant. Otherwise new memory is allocated for each line returned.

Examples
use std::borrow::Cow;
use textwrap::Wrapper;

let wrap20 = Wrapper::new(20);
let mut wrap20_iter = wrap20.wrap_iter("Zero-cost abstractions.");
assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
assert_eq!(wrap20_iter.next(), None);

let wrap25 = Wrapper::new(25);
let mut wrap25_iter = wrap25.wrap_iter("Zero-cost abstractions.");
assert_eq!(wrap25_iter.next(), Some(Cow::from("Zero-cost abstractions.")));
assert_eq!(wrap25_iter.next(), None);

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

The WordSplitter stored in self.splitter is used whenever when a word is too large to fit on the current line. By changing the field, different hyphenation strategies can be implemented.

Complexities

This method consumes the Wrapper and returns a IntoWrapIter iterator. Fully processing the iterator has the same O(n) time complexity as wrap_iter, where n is the length of the input string.

Examples
use std::borrow::Cow;
use textwrap::Wrapper;

let wrap20 = Wrapper::new(20);
let mut wrap20_iter = wrap20.into_wrap_iter("Zero-cost abstractions.");
assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
assert_eq!(wrap20_iter.next(), None);

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.