Struct textwrap::Options

pub struct Options<'a, S: ?Sized = Box<dyn WordSplitter>> {
    pub width: usize,
    pub initial_indent: &'a str,
    pub subsequent_indent: &'a str,
    pub break_words: bool,
    pub wrap_algorithm: WrapAlgorithm,
    pub splitter: S,
}

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: WrapAlgorithm

Wraping algorithm to use, see core::WrapAlgorithm for details.

splitter: S

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 WordSplitter trait for details.

Implementations

impl<'a> Options<'a, 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 HyphenSplitter. Equivalent to

Options {
    width: width,
    initial_indent: "",
    subsequent_indent: "",
    break_words: true,
    #[cfg(feature = "smawk")]
    wrap_algorithm: textwrap::core::WrapAlgorithm::OptimalFit,
    #[cfg(not(feature = "smawk"))]
    wrap_algorithm: textwrap::core::WrapAlgorithm::FirstFit,
    splitter: HyphenSplitter,
}

Note that the default wrap algorithm changes based on the smawk Cargo feature. The best available algorithm is used by default.

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

Dynamic dispatch on the other hand, mean that the splitter is stored as a trait object for instance in a Box<dyn WordSplitter>. This way the 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 WordSplitter>>.

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

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

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

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

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

// uses NoHyphenation with dynamic dispatch
// the actual type: Options<Box<dyn WordSplitter>>
let opt: Options = Options::new(width).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 splitter at run-time without changing the variables type.

impl<'a, S> Options<'a, S>

pub const fn with_splitter(width: usize, splitter: S) -> Self

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

Options {
    width: width,
    initial_indent: "",
    subsequent_indent: "",
    break_words: true,
    #[cfg(feature = "smawk")]
    wrap_algorithm: textwrap::core::WrapAlgorithm::OptimalFit,
    #[cfg(not(feature = "smawk"))]
    wrap_algorithm: textwrap::core::WrapAlgorithm::FirstFit,
    splitter: splitter,
}

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

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

// 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 = Options::with_splitter(width, Box::new(NoHyphenation));
// Its type is actually: `Options<Box<dyn WordSplitter>>`:
let opt_coerced: Options<Box<dyn WordSplitter>> = opt;

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

Since the 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 splitter at run time as seen above, static dispatch especially can store the splitter directly, without the need for a box. This in turn allows it to be used in constant and static context:

use textwrap::{HyphenSplitter, Options};

const FOO: Options<HyphenSplitter> = Options::with_splitter(width, HyphenSplitter);
static BAR: Options<HyphenSplitter> = FOO;

impl<'a, S: WordSplitter> Options<'a, S>

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 wrap_algorithm(self, wrap_algorithm: WrapAlgorithm) -> Self

Change self.wrap_algorithm.

See core::WrapAlgorithm for details on the choices.

pub fn splitter<T>(self, splitter: T) -> Options<'a, T>

Change self.splitter. The 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::{HyphenSplitter, NoHyphenation, Options};
// The default type returned by `new` is `Options<HyphenSplitter>`
let opt: Options<HyphenSplitter> = Options::new(80);
// Setting a different splitter changes the type
let opt: Options<NoHyphenation> = opt.splitter(NoHyphenation);

Trait Implementations

impl<'a, S: Clone + ?Sized> Clone for Options<'a, S>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, S: Debug + ?Sized> Debug for Options<'a, S>

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

Formats the value using the given formatter.

impl<'a, S: ?Sized> From<&'a Options<'a, S>> for Options<'a, &'a S>

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

Performs the conversion.

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

fn from(width: usize) -> Self

Performs the conversion.