Enum textwrap::wrap_algorithms::WrapAlgorithm

pub enum WrapAlgorithm {
    FirstFit,
    OptimalFit(Penalties),
    Custom(for<'a, 'b> fn(words: &'b [Word<'a>], line_widths: &'b [usize]) -> Vec<&'b [Word<'a>]>),
}

Describes how to wrap words into lines.

The simplest approach is to wrap words one word at a time and accept the first way of wrapping which fit (WrapAlgorithm::FirstFit). If the smawk Cargo feature is enabled, a more complex algorithm is available which will look at an entire paragraph at a time in order to find optimal line breaks (WrapAlgorithm::OptimalFit).

Variants

FirstFit

Wrap words using a fast and simple algorithm.

This algorithm uses no look-ahead when finding line breaks. Implemented by wrap_first_fit(), please see that function for details and examples.

OptimalFit(Penalties)

Wrap words using an advanced algorithm with look-ahead.

This wrapping algorithm considers the entire paragraph to find optimal line breaks. When wrapping text, “penalties” are assigned to line breaks based on the gaps left at the end of lines. See Penalties for details.

The underlying wrapping algorithm is implemented by wrap_optimal_fit(), please see that function for examples.

Note: Only available when the smawk Cargo feature is enabled.

Custom(for<'a, 'b> fn(words: &'b [Word<'a>], line_widths: &'b [usize]) -> Vec<&'b [Word<'a>]>)

Custom wrapping function.

Use this if you want to implement your own wrapping algorithm. The function can freely decide how to turn a slice of Words into lines.

Example

use textwrap::core::Word;
use textwrap::{wrap, Options, WrapAlgorithm};

fn stair<'a, 'b>(words: &'b [Word<'a>], _: &'b [usize]) -> Vec<&'b [Word<'a>]> {
    let mut lines = Vec::new();
    let mut step = 1;
    let mut start_idx = 0;
    while start_idx + step <= words.len() {
      lines.push(&words[start_idx .. start_idx+step]);
      start_idx += step;
      step += 1;
    }
    lines
}

let options = Options::new(10).wrap_algorithm(WrapAlgorithm::Custom(stair));
assert_eq!(wrap("First, second, third, fourth, fifth, sixth", options),
           vec!["First,",
                "second, third,",
                "fourth, fifth, sixth"]);

Implementations

impl WrapAlgorithm

pub const fn new() -> Self

Create new wrap algorithm.

The best wrapping algorithm is used by default, i.e., WrapAlgorithm::OptimalFit if available, otherwise WrapAlgorithm::FirstFit.

pub const fn new_optimal_fit() -> Self

New WrapAlgorithm::OptimalFit with default penalties. This works well for monospace text.

Note: Only available when the smawk Cargo feature is enabled.

pub fn wrap<'a, 'b>( &self, words: &'b [Word<'a>], line_widths: &'b [usize], ) -> Vec<&'b [Word<'a>]>

Wrap words according to line widths.

The line_widths slice gives the target line width for each line (the last slice element is repeated as necessary). This can be used to implement hanging indentation.

Trait Implementations

impl Clone for WrapAlgorithm

fn clone(&self) -> WrapAlgorithm

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for WrapAlgorithm

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

Formats the value using the given formatter.

impl Default for WrapAlgorithm

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for WrapAlgorithm

fn eq(&self, other: &Self) -> bool

Compare two wrap algorithms.

use textwrap::WrapAlgorithm;

assert_eq!(WrapAlgorithm::FirstFit, WrapAlgorithm::FirstFit);
#[cfg(feature = "smawk")] {
    assert_eq!(WrapAlgorithm::new_optimal_fit(), WrapAlgorithm::new_optimal_fit());
}

Note that WrapAlgorithm::Custom values never compare equal:

use textwrap::WrapAlgorithm;

assert_ne!(WrapAlgorithm::Custom(|words, line_widths| vec![words]),
           WrapAlgorithm::Custom(|words, line_widths| vec![words]));

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for WrapAlgorithm