pub struct Wrapper<'a, S: WordSplitter> {
pub width: usize,
pub initial_indent: &'a str,
pub subsequent_indent: &'a str,
pub break_words: bool,
pub splitter: S,
}
Expand description
A Wrapper holds settings for wrapping and filling text. Use it
when the convenience wrap_iter
, wrap
and fill
functions
are not flexible enough.
The algorithm used by the WrapIter
iterator (returned from the
wrap_iter
method) works by doing successive partial scans over
words in the input string (where each single scan yields a single
line) so that the overall time and memory complexity is O(n) where
n is the length of the input string.
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.
subsequent_indent: &'a str
Indentation used for subsequent lines of output.
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
.
splitter: S
The method for splitting words. If the hyphenation
feature
is enabled, you can use a hyphenation::Standard
dictionary
here to get language-aware hyphenation.
Implementations
sourceimpl<'a> Wrapper<'a, HyphenSplitter>
impl<'a> Wrapper<'a, HyphenSplitter>
sourcepub fn new(width: usize) -> Wrapper<'a, HyphenSplitter>
pub fn new(width: usize) -> Wrapper<'a, HyphenSplitter>
Create a new Wrapper for wrapping at the specified width. By
default, we allow words longer than width
to be broken. A
HyphenSplitter
will be used by default for splitting
words. See the WordSplitter
trait for other options.
sourceimpl<'a, S: WordSplitter> Wrapper<'a, S>
impl<'a, S: WordSplitter> Wrapper<'a, S>
sourcepub fn with_splitter(width: usize, splitter: S) -> Wrapper<'a, S>
pub fn with_splitter(width: usize, splitter: S) -> Wrapper<'a, S>
Use the given WordSplitter
to create a new Wrapper for
wrapping at the specified width. By default, we allow words
longer than width
to be broken.
sourcepub fn initial_indent(self, indent: &'a str) -> Wrapper<'a, S>
pub fn initial_indent(self, indent: &'a str) -> Wrapper<'a, S>
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::Wrapper;
let wrapper = Wrapper::new(15).initial_indent(" ");
sourcepub fn subsequent_indent(self, indent: &'a str) -> Wrapper<'a, S>
pub fn subsequent_indent(self, indent: &'a str) -> Wrapper<'a, S>
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::Wrapper;
let wrapper = Wrapper::new(15)
.initial_indent("* ")
.subsequent_indent(" ");
sourcepub fn break_words(self, setting: bool) -> Wrapper<'a, S>
pub fn break_words(self, setting: bool) -> Wrapper<'a, S>
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.
sourcepub fn fill(&self, s: &str) -> String
pub fn fill(&self, s: &str) -> String
Fill a line of text at self.width
characters. Strings are
wrapped based on their displayed width, not their size in
bytes.
The result is a string with newlines between each line. Use
the wrap
method if you need access to the individual lines.
Complexities
This method simply joins the lines produced by wrap_iter
. As
such, it inherits the O(n) time and memory complexity where
n is the input string length.
Examples
use textwrap::Wrapper;
let wrapper = Wrapper::new(15);
assert_eq!(wrapper.fill("Memory safety without garbage collection."),
"Memory safety\nwithout garbage\ncollection.");
sourcepub fn wrap(&self, s: &'a str) -> Vec<Cow<'a, str>>
pub fn wrap(&self, s: &'a str) -> Vec<Cow<'a, str>>
Wrap a line of text at self.width
characters. Strings are
wrapped based on their displayed width, not their size in
bytes.
Complexities
This method simply collects the lines produced by wrap_iter
.
As such, it inherits the O(n) overall time and memory
complexity where n is the input string length.
Examples
use textwrap::Wrapper;
let wrap15 = Wrapper::new(15);
assert_eq!(wrap15.wrap("Concurrency without data races."),
vec!["Concurrency",
"without data",
"races."]);
let wrap20 = Wrapper::new(20);
assert_eq!(wrap20.wrap("Concurrency without data races."),
vec!["Concurrency without",
"data races."]);
Notice that newlines in the input are preserved. This means that they force a line break, regardless of how long the current line is:
use textwrap::Wrapper;
let wrapper = Wrapper::new(40);
assert_eq!(wrapper.wrap("First line.\nSecond line."),
vec!["First line.", "Second line."]);
sourcepub fn wrap_iter<'w>(&'w self, s: &'a str) -> WrapIter<'w, 'a, S>ⓘNotable traits for WrapIter<'w, 'a, S>impl<'w, 'a: 'w, S: WordSplitter> Iterator for WrapIter<'w, 'a, S> type Item = Cow<'a, str>;
pub fn wrap_iter<'w>(&'w self, s: &'a str) -> WrapIter<'w, 'a, S>ⓘNotable traits for WrapIter<'w, 'a, S>impl<'w, 'a: 'w, S: WordSplitter> Iterator for WrapIter<'w, 'a, S> type Item = Cow<'a, str>;
Lazily wrap a line of text at self.width
characters. Strings
are wrapped based on their displayed width, not their size in
bytes.
The WordSplitter
stored in self.splitter
is used
whenever when a word is too large to fit on the current line.
By changing the field, different hyphenation strategies can be
implemented.
Complexities
This method returns a WrapIter
iterator which borrows this
Wrapper
. The algorithm used has a linear complexity, so
getting the next line from the iterator will take O(w) time,
where w is the wrapping width. Fully processing the iterator
will take O(n) time for an input string of length n.
When no indentation is used, each line returned is a slice of the input string and the memory overhead is thus constant. Otherwise new memory is allocated for each line returned.
Examples
use std::borrow::Cow;
use textwrap::Wrapper;
let wrap20 = Wrapper::new(20);
let mut wrap20_iter = wrap20.wrap_iter("Zero-cost abstractions.");
assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
assert_eq!(wrap20_iter.next(), None);
let wrap25 = Wrapper::new(25);
let mut wrap25_iter = wrap25.wrap_iter("Zero-cost abstractions.");
assert_eq!(wrap25_iter.next(), Some(Cow::from("Zero-cost abstractions.")));
assert_eq!(wrap25_iter.next(), None);
sourcepub fn into_wrap_iter(self, s: &'a str) -> IntoWrapIter<'a, S>ⓘNotable traits for IntoWrapIter<'a, S>impl<'a, S: WordSplitter> Iterator for IntoWrapIter<'a, S> type Item = Cow<'a, str>;
pub fn into_wrap_iter(self, s: &'a str) -> IntoWrapIter<'a, S>ⓘNotable traits for IntoWrapIter<'a, S>impl<'a, S: WordSplitter> Iterator for IntoWrapIter<'a, S> type Item = Cow<'a, str>;
Lazily wrap a line of text at self.width
characters. Strings
are wrapped based on their displayed width, not their size in
bytes.
The WordSplitter
stored in self.splitter
is used
whenever when a word is too large to fit on the current line.
By changing the field, different hyphenation strategies can be
implemented.
Complexities
This method consumes the Wrapper
and returns a
IntoWrapIter
iterator. Fully processing the iterator has
the same O(n) time complexity as wrap_iter
, where n is
the length of the input string.
Examples
use std::borrow::Cow;
use textwrap::Wrapper;
let wrap20 = Wrapper::new(20);
let mut wrap20_iter = wrap20.into_wrap_iter("Zero-cost abstractions.");
assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
assert_eq!(wrap20_iter.next(), None);
Trait Implementations
sourceimpl<'a, S: Clone + WordSplitter> Clone for Wrapper<'a, S>
impl<'a, S: Clone + WordSplitter> Clone for Wrapper<'a, S>
Auto Trait Implementations
impl<'a, S> RefUnwindSafe for Wrapper<'a, S> where
S: RefUnwindSafe,
impl<'a, S> Send for Wrapper<'a, S> where
S: Send,
impl<'a, S> Sync for Wrapper<'a, S> where
S: Sync,
impl<'a, S> Unpin for Wrapper<'a, S> where
S: Unpin,
impl<'a, S> UnwindSafe for Wrapper<'a, S> where
S: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more