Struct textwrap::Options

pub struct Options<'a> {
    pub width: usize,
    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

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. 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 wrap_algorithms::WrapAlgorithm trait for details.

word_separator: WordSeparator

The line breaking algorithm to use, see word_separators::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. Equivalent to

Options {
    width: width,
    initial_indent: "",
    subsequent_indent: "",
    break_words: true,
    #[cfg(feature = "unicode-linebreak")]
    word_separator: WordSeparator::UnicodeBreakProperties,
    #[cfg(not(feature = "unicode-linebreak"))]
    word_separator: WordSeparator::AsciiSpace,
    #[cfg(feature = "smawk")]
    wrap_algorithm: WrapAlgorithm::new_optimal_fit(),
    #[cfg(not(feature = "smawk"))]
    wrap_algorithm: WrapAlgorithm::FirstFit,
    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 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.

impl<'a> Options<'a>

pub fn initial_indent(self, 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, 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, setting: 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.

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 word_separators::WordSeparator for details on the choices.

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

Change self.wrap_algorithm.

See the wrap_algorithms::WrapAlgorithm trait for details on the choices.

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

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

Examples

use textwrap::{Options, WordSplitter};
let opt = Options::new(80);
assert_eq!(opt.word_splitter, WordSplitter::HyphenSplitter);
let opt = opt.word_splitter(WordSplitter::NoHyphenation);
assert_eq!(opt.word_splitter, WordSplitter::NoHyphenation);

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

Performs the conversion.

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

fn from(width: usize) -> Self

Performs the conversion.