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,
}
Expand description
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§
source§impl<'a> Options<'a, HyphenSplitter>
impl<'a> Options<'a, HyphenSplitter>
Constructors for boxed Options, specifically.
sourcepub const fn new(width: usize) -> Self
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.
sourcepub fn with_termwidth() -> Self
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.
source§impl<'a, S> Options<'a, S>
impl<'a, S> Options<'a, S>
sourcepub const fn with_splitter(width: usize, splitter: S) -> Self
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;
source§impl<'a, S: WordSplitter> Options<'a, S>
impl<'a, S: WordSplitter> Options<'a, S>
sourcepub fn initial_indent(self, indent: &'a str) -> Self
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."]);
sourcepub fn subsequent_indent(self, indent: &'a str) -> Self
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."]);
sourcepub fn break_words(self, setting: bool) -> Self
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."]);
sourcepub fn wrap_algorithm(self, wrap_algorithm: WrapAlgorithm) -> Self
pub fn wrap_algorithm(self, wrap_algorithm: WrapAlgorithm) -> Self
Change self.wrap_algorithm
.
See core::WrapAlgorithm
for details on the choices.
sourcepub fn splitter<T>(self, splitter: T) -> Options<'a, T>
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);