Struct textwrap::Options

pub struct Options<'a, WrapAlgo = Box<dyn WrapAlgorithm>, WordSep = Box<dyn WordSeparator>, WordSplit = Box<dyn WordSplitter>> {
    pub width: usize,
    pub initial_indent: &'a str,
    pub subsequent_indent: &'a str,
    pub break_words: bool,
    pub wrap_algorithm: WrapAlgo,
    pub word_separator: WordSep,
    pub word_splitter: WordSplit,
}

Holds settings 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: WrapAlgo

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

word_separator: WordSep

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

word_splitter: WordSplit

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. Please see the word_splitters::WordSplitter trait for details.

Implementations

impl<'a> Options<'a, OptimalFit, UnicodeBreakProperties, HyphenSplitter>

Constructors for boxed Options, specifically.

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

Creates a new Options with the specified width and static dispatch using the word_splitters::HyphenSplitter. Equivalent to

Options {
    width: width,
    initial_indent: "",
    subsequent_indent: "",
    break_words: true,
    #[cfg(feature = "unicode-linebreak")]
    word_separator: textwrap::word_separators::UnicodeBreakProperties,
    #[cfg(not(feature = "unicode-linebreak"))]
    word_separator: textwrap::word_separators::AsciiSpace,
    #[cfg(feature = "smawk")]
    wrap_algorithm: textwrap::wrap_algorithms::OptimalFit,
    #[cfg(not(feature = "smawk"))]
    wrap_algorithm: textwrap::wrap_algorithms::FirstFit,
    word_splitter: textwrap::word_splitters::HyphenSplitter,
}

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

Static dispatch means here, that the word splitter is stored as-is and the type is known at compile-time. Thus the returned value is actually a Options<AsciiSpace, HyphenSplitter>.

Dynamic dispatch on the other hand, means that the word separator and/or word splitter is stored as a trait object such as a Box<dyn word_splitters::WordSplitter>. This way the word splitter's inner type can be changed without changing the type of this struct, which then would be just Options as a short cut for Options<Box<dyn word_separators::WordSeparator>, Box<dyn word_splitters::WordSplitter>>.

The value and type of the word splitter can be choose from the start using the Options::with_word_splitter constructor or changed afterwards using the Options::word_splitter method. Whether static or dynamic dispatch is used, depends on whether these functions are given a boxed word_splitters::WordSplitter or not. Take for example:

use textwrap::Options;
use textwrap::word_splitters::{HyphenSplitter, NoHyphenation};

// uses HyphenSplitter with static dispatch
// the actual type: Options<AsciiSpace, HyphenSplitter>
let opt = Options::new(width);

// uses NoHyphenation with static dispatch
// the actual type: Options<AsciiSpace, NoHyphenation>
let opt = Options::new(width).word_splitter(NoHyphenation);

// uses HyphenSplitter with dynamic dispatch
// the actual type: Options<AsciiSpace, Box<dyn word_splitters::WordSplitter>>
let opt: Options<_, _, _> = Options::new(width).word_splitter(Box::new(HyphenSplitter));

// uses NoHyphenation with dynamic dispatch
// the actual type: Options<AsciiSpace, Box<dyn word_splitters::WordSplitter>>
let opt: Options<_, _, _> = Options::new(width).word_splitter(Box::new(NoHyphenation));

Notice that the last two variables have the same type, despite the different WordSplitter in use. Thus dynamic dispatch allows to change the word splitter at run-time without changing the variables type.

impl<'a, WordSplit> Options<'a, OptimalFit, UnicodeBreakProperties, WordSplit>

pub const fn with_word_splitter(width: usize, word_splitter: WordSplit) -> Self

Creates a new Options with the specified width and word splitter. Equivalent to

Options {
    width: width,
    initial_indent: "",
    subsequent_indent: "",
    break_words: true,
    #[cfg(feature = "unicode-linebreak")]
    word_separator: textwrap::word_separators::UnicodeBreakProperties,
    #[cfg(not(feature = "unicode-linebreak"))]
    word_separator: textwrap::word_separators::AsciiSpace,
    #[cfg(feature = "smawk")]
    wrap_algorithm: textwrap::wrap_algorithms::OptimalFit,
    #[cfg(not(feature = "smawk"))]
    wrap_algorithm: textwrap::wrap_algorithms::FirstFit,
    word_splitter: word_splitter,
}

This constructor allows to specify the word splitter to be used. It is like a short-cut for Options::new(w).word_splitter(s), but this function is a const fn. The given word splitter may be in a Box, which then can be coerced into a trait object for dynamic dispatch:

use textwrap::Options;
use textwrap::word_splitters::{HyphenSplitter, NoHyphenation, WordSplitter};

// This opt contains a boxed trait object as splitter.
// The type annotation is important, otherwise it will be not a trait object
let mut opt: Options<_, _, Box<dyn WordSplitter>>
    = Options::with_word_splitter(width, Box::new(NoHyphenation));
// Its type is actually: `Options<AsciiSpace, Box<dyn word_splitters::WordSplitter>>`:
let opt_coerced: Options<_, _, Box<dyn WordSplitter>> = opt;

// Thus, it can be overridden with a different word splitter.
opt = Options::with_word_splitter(width, Box::new(HyphenSplitter));
// Now, containing a `HyphenSplitter` instead.

Since the word splitter is given by value, which determines the generic type parameter, it can be used to produce both an Options with static and dynamic dispatch, respectively. While dynamic dispatch allows to change the type of the inner word splitter at run time as seen above, static dispatch especially can store the word splitter directly, without the need for a box. This in turn allows it to be used in constant and static context:

use textwrap::word_splitters::HyphenSplitter; use textwrap::{ Options};
use textwrap::word_separators::AsciiSpace;
use textwrap::wrap_algorithms::FirstFit;

const FOO: Options<FirstFit, AsciiSpace, HyphenSplitter> =
    Options::with_word_splitter(width, HyphenSplitter);
static BAR: Options<FirstFit, AsciiSpace, HyphenSplitter> = FOO;

impl<'a, WrapAlgo, WordSep, WordSplit> Options<'a, WrapAlgo, WordSep, WordSplit>

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

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

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<NewWordSep>(
    self,
    word_separator: NewWordSep
) -> Options<'a, WrapAlgo, NewWordSep, WordSplit>

Change self.word_separator.

See word_separators::WordSeparator for details on the choices.

pub fn wrap_algorithm<NewWrapAlgo>(
    self,
    wrap_algorithm: NewWrapAlgo
) -> Options<'a, NewWrapAlgo, WordSep, WordSplit>

Change self.wrap_algorithm.

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

pub fn word_splitter<NewWordSplit>(
    self,
    word_splitter: NewWordSplit
) -> Options<'a, WrapAlgo, WordSep, NewWordSplit>

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

This function may return a different type than Self. That is the case when the given splitter is of a different type the the currently stored one in the splitter field. Take for example:

use textwrap::word_splitters::{HyphenSplitter, NoHyphenation};
use textwrap::Options;
// The default type returned by `new`:
let opt: Options<_, _, HyphenSplitter> = Options::new(80);
// Setting a different word splitter changes the type
let opt: Options<_, _, NoHyphenation> = opt.word_splitter(NoHyphenation);

Trait Implementations

impl<'a, WrapAlgo: Clone, WordSep: Clone, WordSplit: Clone> Clone for Options<'a, WrapAlgo, WordSep, WordSplit>

fn clone(&self) -> Options<'a, WrapAlgo, WordSep, WordSplit>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, WrapAlgo: Debug, WordSep: Debug, WordSplit: Debug> Debug for Options<'a, WrapAlgo, WordSep, WordSplit>

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

Formats the value using the given formatter.

impl<'a, WrapAlgo, WordSep, WordSplit> From<&'a Options<'a, WrapAlgo, WordSep, WordSplit>> for Options<'a, WrapAlgo, WordSep, WordSplit> where
    WrapAlgo: Clone,
    WordSep: Clone,
    WordSplit: Clone, 

fn from(options: &'a Options<'a, WrapAlgo, WordSep, WordSplit>) -> Self

Performs the conversion.

impl<'a> From<usize> for Options<'a, OptimalFit, UnicodeBreakProperties, HyphenSplitter>

fn from(width: usize) -> Self

Performs the conversion.