Struct textwrap::Options

#[non_exhaustive]
pub struct Options<'a> {
    pub width: usize,
    pub line_ending: LineEnding,
    pub initial_indent: &'a str,
    pub subsequent_indent: &'a str,
    pub break_words: bool,
    pub wrap_algorithm: WrapAlgorithm,
    pub word_separator: WordSeparator,
    pub word_splitter: WordSplitter,
}

Holds configuration options for wrapping and filling text.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

width: usize

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

line_ending: LineEnding

Line ending used for breaking lines.

initial_indent: &'a str

Indentation used for the first line of output. See the Options::initial_indent method.

subsequent_indent: &'a str

Indentation used for subsequent lines of output. See the Options::subsequent_indent method.

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. See the Options::break_words method.

wrap_algorithm: WrapAlgorithm

Wrapping algorithm to use, see the implementations of the WrapAlgorithm trait for details.

word_separator: WordSeparator

The line breaking algorithm to use, see the WordSeparator trait for an overview and possible implementations.

word_splitter: WordSplitter

The method for splitting words. This can be used to prohibit splitting words on hyphens, or it can be used to implement language-aware machine hyphenation.

Implementations

impl<'a> Options<'a>

pub const fn new(width: usize) -> Self

Creates a new Options with the specified width.

The other fields are given default values as follows:

let options = Options::new(width);
assert_eq!(options.line_ending, LineEnding::LF);
assert_eq!(options.initial_indent, "");
assert_eq!(options.subsequent_indent, "");
assert_eq!(options.break_words, true);

#[cfg(feature = "unicode-linebreak")]
assert_eq!(options.word_separator, WordSeparator::UnicodeBreakProperties);
#[cfg(not(feature = "unicode-linebreak"))]
assert_eq!(options.word_separator, WordSeparator::AsciiSpace);

#[cfg(feature = "smawk")]
assert_eq!(options.wrap_algorithm, WrapAlgorithm::new_optimal_fit());
#[cfg(not(feature = "smawk"))]
assert_eq!(options.wrap_algorithm, WrapAlgorithm::FirstFit);

assert_eq!(options.word_splitter, WordSplitter::HyphenSplitter);

Note that the default word separator and wrap algorithms changes based on the available Cargo features. The best available algorithms are used by default.

pub fn line_ending(self, line_ending: LineEnding) -> Self

Change self.line_ending. This specifies which of the supported line endings should be used to break the lines of the input text.

Examples

use textwrap::{refill, LineEnding, Options};

let options = Options::new(15).line_ending(LineEnding::CRLF);
assert_eq!(refill("This is a little example.", options),
           "This is a\r\nlittle example.");

pub fn width(self, width: usize) -> Self

Set self.width to the given value.

pub fn initial_indent(self, initial_indent: &'a str) -> Self

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::{wrap, Options};

let options = Options::new(16).initial_indent("    ");
assert_eq!(wrap("This is a little example.", options),
           vec!["    This is a",
                "little example."]);

pub fn subsequent_indent(self, subsequent_indent: &'a str) -> Self

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::{wrap, Options};

let options = Options::new(12)
    .initial_indent("* ")
    .subsequent_indent("  ");
#[cfg(feature = "smawk")]
assert_eq!(wrap("This is a little example.", options),
           vec!["* This is",
                "  a little",
                "  example."]);

// Without the `smawk` feature, the wrapping is a little different:
#[cfg(not(feature = "smawk"))]
assert_eq!(wrap("This is a little example.", options),
           vec!["* This is a",
                "  little",
                "  example."]);

pub fn break_words(self, break_words: bool) -> Self

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.

See Options::word_splitter instead if you want to control hyphenation.

Examples

use textwrap::{wrap, Options};

let options = Options::new(4).break_words(true);
assert_eq!(wrap("This is a little example.", options),
           vec!["This",
                "is a",
                "litt",
                "le",
                "exam",
                "ple."]);

pub fn word_separator(self, word_separator: WordSeparator) -> Options<'a>

Change self.word_separator.

See the WordSeparator trait for details on the choices.

pub fn wrap_algorithm(self, wrap_algorithm: WrapAlgorithm) -> Options<'a>

Change self.wrap_algorithm.

See the WrapAlgorithm trait for details on the choices.

pub fn word_splitter(self, word_splitter: WordSplitter) -> Options<'a>

Change self.word_splitter. The WordSplitter is used to fit part of a word into the current line when wrapping text.

See Options::break_words instead if you want to control the handling of words longer than the line width.

Examples

use textwrap::{wrap, Options, WordSplitter};

// The default is WordSplitter::HyphenSplitter.
let options = Options::new(5);
assert_eq!(wrap("foo-bar-baz", &options),
           vec!["foo-", "bar-", "baz"]);

// The word is now so long that break_words kick in:
let options = Options::new(5)
    .word_splitter(WordSplitter::NoHyphenation);
assert_eq!(wrap("foo-bar-baz", &options),
           vec!["foo-b", "ar-ba", "z"]);

// If you want to breaks at all, disable both:
let options = Options::new(5)
    .break_words(false)
    .word_splitter(WordSplitter::NoHyphenation);
assert_eq!(wrap("foo-bar-baz", &options),
           vec!["foo-bar-baz"]);

impl<'a> Options<'a>

pub fn with_termwidth() -> Self

Creates a new Options with width set to the current terminal width. If the terminal width cannot be determined (typically because the standard input and output is not connected to a terminal), a width of 80 characters will be used. Other settings use the same defaults as Options::new.

Equivalent to:

use textwrap::{termwidth, Options};

let options = Options::new(termwidth());

Note: Only available when the terminal_size feature is enabled.

Trait Implementations

impl<'a> Clone for Options<'a>

fn clone(&self) -> Options<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Options<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<&'a Options<'a>> for Options<'a>

fn from(options: &'a Options<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<usize> for Options<'a>

fn from(width: usize) -> Self

Converts to this type from the input type.