1 //! `textwrap` provides functions for word wrapping and filling text.
3 //! Wrapping text can be very useful in commandline programs where you
4 //! want to format dynamic output nicely so it looks good in a
5 //! terminal. A quick example:
8 //! extern crate textwrap;
9 //! use textwrap::fill;
12 //! let text = "textwrap: a small library for wrapping text.";
13 //! println!("{}", fill(text, 18));
17 //! This will display the following output:
25 //! # Displayed Width vs Byte Size
27 //! To word wrap text, one must know the width of each word so one can
28 //! know when to break lines. This library measures the width of text
29 //! using the [displayed width][unicode-width], not the size in bytes.
31 //! This is important for non-ASCII text. ASCII characters such as `a`
32 //! and `!` are simple and take up one column each. This means that
33 //! the displayed width is equal to the string length in bytes.
34 //! However, non-ASCII characters and symbols take up more than one
35 //! byte when UTF-8 encoded: `é` is `0xc3 0xa9` (two bytes) and `⚙` is
36 //! `0xe2 0x9a 0x99` (three bytes) in UTF-8, respectively.
38 //! This is why we take care to use the displayed width instead of the
39 //! byte count when computing line lengths. All functions in this
40 //! library handle Unicode characters like this.
42 //! [unicode-width]: https://docs.rs/unicode-width/
44 #![doc(html_root_url = "https://docs.rs/textwrap/0.8.0")]
45 #![deny(missing_docs)]
47 extern crate unicode_width
;
48 extern crate term_size
;
49 #[cfg(feature = "hyphenation")]
50 extern crate hyphenation
;
53 use std
::str::CharIndices
;
55 use unicode_width
::UnicodeWidthStr
;
56 use unicode_width
::UnicodeWidthChar
;
57 #[cfg(feature = "hyphenation")]
58 use hyphenation
::{Hyphenation, Corpus}
;
60 /// A non-breaking space.
61 const NBSP
: char = '
\u{a0}'
;
63 /// An interface for splitting words.
65 /// When the [`wrap_iter`] method will try to fit text into a line, it
66 /// will eventually find a word that it too large the current text
67 /// width. It will then call the currently configured `WordSplitter` to
68 /// have it attempt to split the word into smaller parts. This trait
69 /// describes that functionality via the [`split`] method.
71 /// If the `textwrap` crate has been compiled with the `hyphenation`
72 /// feature enabled, you will find an implementation of `WordSplitter`
73 /// by the `hyphenation::language::Corpus` struct. Use this struct for
74 /// language-aware hyphenation. See the [`hyphenation` documentation]
77 /// [`wrap_iter`]: struct.Wrapper.html#method.wrap_iter
78 /// [`split`]: #tymethod.split
79 /// [`hyphenation` documentation]: https://docs.rs/hyphenation/
80 pub trait WordSplitter
{
81 /// Return all possible splits of word. Each split is a triple
82 /// with a head, a hyphen, and a tail where `head + &hyphen +
83 /// &tail == word`. The hyphen can be empty if there is already a
84 /// hyphen in the head.
86 /// The splits should go from smallest to longest and should
87 /// include no split at all. So the word "technology" could be
91 /// vec![("tech", "-", "nology"),
92 /// ("technol", "-", "ogy"),
93 /// ("technolo", "-", "gy"),
94 /// ("technology", "", "")];
96 fn split
<'w
>(&self, word
: &'w
str) -> Vec
<(&'w
str, &'w
str, &'w
str)>;
99 /// Use this as a [`Wrapper.splitter`] to avoid any kind of
103 /// use textwrap::{Wrapper, NoHyphenation};
105 /// let wrapper = Wrapper::with_splitter(8, NoHyphenation);
106 /// assert_eq!(wrapper.wrap("foo bar-baz"), vec!["foo", "bar-baz"]);
109 /// [`Wrapper.splitter`]: struct.Wrapper.html#structfield.splitter
111 pub struct NoHyphenation
;
113 /// `NoHyphenation` implements `WordSplitter` by not splitting the
115 impl WordSplitter
for NoHyphenation
{
116 fn split
<'w
>(&self, word
: &'w
str) -> Vec
<(&'w
str, &'w
str, &'w
str)> {
121 /// Simple and default way to split words: splitting on existing
124 /// You probably don't need to use this type since it's already used
125 /// by default by `Wrapper::new`.
127 pub struct HyphenSplitter
;
129 /// `HyphenSplitter` is the default `WordSplitter` used by
130 /// `Wrapper::new`. It will split words on any existing hyphens in the
133 /// It will only use hyphens that are surrounded by alphanumeric
134 /// characters, which prevents a word like "--foo-bar" from being
135 /// split on the first or second hyphen.
136 impl WordSplitter
for HyphenSplitter
{
137 fn split
<'w
>(&self, word
: &'w
str) -> Vec
<(&'w
str, &'w
str, &'w
str)> {
138 let mut triples
= Vec
::new();
139 // Split on hyphens, smallest split first. We only use hyphens
140 // that are surrounded by alphanumeric characters. This is to
141 // avoid splitting on repeated hyphens, such as those found in
143 let mut char_indices
= word
.char_indices();
144 // Early return if the word is empty.
145 let mut prev
= match char_indices
.next() {
146 None
=> return vec
![(word
, "", "")],
150 // Find current word, or return early if the word only has a
152 let (mut idx
, mut cur
) = match char_indices
.next() {
153 None
=> return vec
![(word
, "", "")],
154 Some((idx
, cur
)) => (idx
, cur
),
157 for (i
, next
) in char_indices
{
158 if prev
.is_alphanumeric() && cur
== '
-'
&& next
.is_alphanumeric() {
159 let (head
, tail
) = word
.split_at(idx
+ 1);
160 triples
.push((head
, "", tail
));
167 // Finally option is no split at all.
168 triples
.push((word
, "", ""));
174 /// A hyphenation Corpus can be used to do language-specific
175 /// hyphenation using patterns from the hyphenation crate.
176 #[cfg(feature = "hyphenation")]
177 impl WordSplitter
for Corpus
{
178 fn split
<'w
>(&self, word
: &'w
str) -> Vec
<(&'w
str, &'w
str, &'w
str)> {
179 // Find splits based on language corpus.
180 let mut triples
= Vec
::new();
181 for n
in word
.opportunities(self) {
182 let (head
, tail
) = word
.split_at(n
);
183 let hyphen
= if head
.ends_with('
-'
) { "" }
else { "-" }
;
184 triples
.push((head
, hyphen
, tail
));
186 // Finally option is no split at all.
187 triples
.push((word
, "", ""));
193 /// Backport of the `AddAssign` trait implementation from Rust 1.14.
194 fn cow_add_assign
<'a
>(lhs
: &mut Cow
<'a
, str>, rhs
: &'a
str) {
196 *lhs
= Cow
::Borrowed(rhs
)
197 } else if rhs
.is_empty() {
200 if let Cow
::Borrowed(inner
) = *lhs
{
201 let mut s
= String
::with_capacity(lhs
.len() + rhs
.len());
203 *lhs
= Cow
::Owned(s
);
205 lhs
.to_mut().push_str(rhs
);
210 /// A Wrapper holds settings for wrapping and filling text. Use it
211 /// when the convenience [`wrap_iter`], [`wrap`] and [`fill`] functions
212 /// are not flexible enough.
214 /// [`wrap_iter`]: fn.wrap_iter.html
215 /// [`wrap`]: fn.wrap.html
216 /// [`fill`]: fn.fill.html
218 /// The algorithm used by the `WrapIter` iterator (returned from the
219 /// `wrap_iter` method) works by doing successive partial scans over
220 /// words in the input string (where each single scan yields a single
221 /// line) so that the overall time and memory complexity is O(*n*) where
222 /// *n* is the length of the input string.
224 pub struct Wrapper
<'a
, S
: WordSplitter
> {
225 /// The width in columns at which the text will be wrapped.
227 /// Indentation used for the first line of output.
228 pub initial_indent
: &'a
str,
229 /// Indentation used for subsequent lines of output.
230 pub subsequent_indent
: &'a
str,
231 /// Allow long words to be broken if they cannot fit on a line.
232 /// When set to `false`, some lines be being longer than
234 pub break_words
: bool
,
235 /// The method for splitting words. If the `hyphenation` feature
236 /// is enabled, you can use a `hyphenation::language::Corpus` here
237 /// to get language-aware hyphenation.
241 impl<'a
> Wrapper
<'a
, HyphenSplitter
> {
242 /// Create a new Wrapper for wrapping at the specified width. By
243 /// default, we allow words longer than `width` to be broken. A
244 /// [`HyphenSplitter`] will be used by default for splitting
245 /// words. See the [`WordSplitter`] trait for other options.
247 /// [`HyphenSplitter`]: struct.HyphenSplitter.html
248 /// [`WordSplitter`]: trait.WordSplitter.html
249 pub fn new(width
: usize) -> Wrapper
<'a
, HyphenSplitter
> {
250 Wrapper
::with_splitter(width
, HyphenSplitter
)
253 /// Create a new Wrapper for wrapping text at the current terminal
254 /// width. If the terminal width cannot be determined (typically
255 /// because the standard input and output is not connected to a
256 /// terminal), a width of 80 characters will be used. Other
257 /// settings use the same defaults as `Wrapper::new`.
262 /// use textwrap::{Wrapper, termwidth};
264 /// let wrapper = Wrapper::new(termwidth());
266 pub fn with_termwidth() -> Wrapper
<'a
, HyphenSplitter
> {
267 Wrapper
::new(termwidth())
271 impl<'w
, 'a
: 'w
, S
: WordSplitter
> Wrapper
<'a
, S
> {
272 /// Use the given [`WordSplitter`] to create a new Wrapper for
273 /// wrapping at the specified width. By default, we allow words
274 /// longer than `width` to be broken.
276 /// [`WordSplitter`]: trait.WordSplitter.html
277 pub fn with_splitter(width
: usize, splitter
: S
) -> Wrapper
<'a
, S
> {
281 subsequent_indent
: "",
287 /// Change [`self.initial_indent`]. The initial indentation is
288 /// used on the very first line of output.
292 /// Classic paragraph indentation can be achived by specifying an
293 /// initial indentation and wrapping each paragraph by itself:
296 /// use textwrap::Wrapper;
298 /// let wrapper = Wrapper::new(15).initial_indent(" ");
301 /// [`self.initial_indent`]: #structfield.initial_indent
302 pub fn initial_indent(self, indent
: &'a
str) -> Wrapper
<'a
, S
> {
303 Wrapper { initial_indent: indent, ..self }
306 /// Change [`self.subsequent_indent`]. The subsequent indentation
307 /// is used on lines following the first line of output.
311 /// Combining initial and subsequent indentation lets you format a
312 /// single paragraph as a bullet list:
315 /// use textwrap::Wrapper;
317 /// let wrapper = Wrapper::new(15)
318 /// .initial_indent("* ")
319 /// .subsequent_indent(" ");
322 /// [`self.subsequent_indent`]: #structfield.subsequent_indent
323 pub fn subsequent_indent(self, indent
: &'a
str) -> Wrapper
<'a
, S
> {
324 Wrapper { subsequent_indent: indent, ..self }
327 /// Change [`self.break_words`]. This controls if words longer
328 /// than `self.width` can be broken, or if they will be left
329 /// sticking out into the right margin.
331 /// [`self.break_words`]: #structfield.break_words
332 pub fn break_words(self, setting
: bool
) -> Wrapper
<'a
, S
> {
333 Wrapper { break_words: setting, ..self }
336 /// Fill a line of text at `self.width` characters. Strings are
337 /// wrapped based on their displayed width, not their size in
340 /// The result is a string with newlines between each line. Use
341 /// the `wrap` method if you need access to the individual lines.
345 /// This method simply joins the lines produced by `wrap_iter`. As
346 /// such, it inherits the O(*n*) time and memory complexity where
347 /// *n* is the input string length.
352 /// use textwrap::Wrapper;
354 /// let wrapper = Wrapper::new(15);
355 /// assert_eq!(wrapper.fill("Memory safety without garbage collection."),
356 /// "Memory safety\nwithout garbage\ncollection.");
358 pub fn fill(&self, s
: &str) -> String
{
359 let mut result
= String
::new();
361 for (i
, line
) in self.wrap_iter(s
).enumerate() {
363 result
.push_str("\n");
366 result
.push_str(&line
);
372 /// Wrap a line of text at `self.width` characters. Strings are
373 /// wrapped based on their displayed width, not their size in
378 /// This method simply collects the lines produced by `wrap_iter`.
379 /// As such, it inherits the O(*n*) overall time and memory
380 /// complexity where *n* is the input string length.
385 /// use textwrap::Wrapper;
387 /// let wrap15 = Wrapper::new(15);
388 /// assert_eq!(wrap15.wrap("Concurrency without data races."),
389 /// vec!["Concurrency",
393 /// let wrap20 = Wrapper::new(20);
394 /// assert_eq!(wrap20.wrap("Concurrency without data races."),
395 /// vec!["Concurrency without",
398 pub fn wrap(&self, s
: &'a
str) -> Vec
<Cow
<'a
, str>> {
399 self.wrap_iter(s
).collect
::<Vec
<_
>>()
402 /// Lazily wrap a line of text at `self.width` characters. Strings
403 /// are wrapped based on their displayed width, not their size in
406 /// The [`WordSplitter`] stored in [`self.splitter`] is used
407 /// whenever when a word is too large to fit on the current line.
408 /// By changing the field, different hyphenation strategies can be
413 /// This method returns a [`WrapIter`] iterator which borrows this
414 /// `Wrapper`. The algorithm used has a linear complexity, so
415 /// getting the next line from the iterator will take O(*w*) time,
416 /// where *w* is the wrapping width. Fully processing the iterator
417 /// will take O(*n*) time for an input string of length *n*.
419 /// When no indentation is used, each line returned is a slice of
420 /// the input string and the memory overhead is thus constant.
421 /// Otherwise new memory is allocated for each line returned.
426 /// use std::borrow::Cow;
427 /// use textwrap::Wrapper;
429 /// let wrap20 = Wrapper::new(20);
430 /// let mut wrap20_iter = wrap20.wrap_iter("Zero-cost abstractions.");
431 /// assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
432 /// assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
433 /// assert_eq!(wrap20_iter.next(), None);
435 /// let wrap25 = Wrapper::new(25);
436 /// let mut wrap25_iter = wrap25.wrap_iter("Zero-cost abstractions.");
437 /// assert_eq!(wrap25_iter.next(), Some(Cow::from("Zero-cost abstractions.")));
438 /// assert_eq!(wrap25_iter.next(), None);
441 /// [`self.splitter`]: #structfield.splitter
442 /// [`WordSplitter`]: trait.WordSplitter.html
443 /// [`WrapIter`]: struct.WrapIter.html
444 pub fn wrap_iter(&'w
self, s
: &'a
str) -> WrapIter
<'w
, 'a
, S
> {
447 wrap_iter_impl
: WrapIterImpl
::new(self, s
),
451 /// Lazily wrap a line of text at `self.width` characters. Strings
452 /// are wrapped based on their displayed width, not their size in
455 /// The [`WordSplitter`] stored in [`self.splitter`] is used
456 /// whenever when a word is too large to fit on the current line.
457 /// By changing the field, different hyphenation strategies can be
462 /// This method consumes the `Wrapper` and returns a
463 /// [`IntoWrapIter`] iterator. Fully processing the iterator has
464 /// the same O(*n*) time complexity as [`wrap_iter`], where *n* is
465 /// the length of the input string.
470 /// use std::borrow::Cow;
471 /// use textwrap::Wrapper;
473 /// let wrap20 = Wrapper::new(20);
474 /// let mut wrap20_iter = wrap20.into_wrap_iter("Zero-cost abstractions.");
475 /// assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
476 /// assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
477 /// assert_eq!(wrap20_iter.next(), None);
480 /// [`self.splitter`]: #structfield.splitter
481 /// [`WordSplitter`]: trait.WordSplitter.html
482 /// [`IntoWrapIter`]: struct.IntoWrapIter.html
483 /// [`wrap_iter`]: #method.wrap_iter
484 pub fn into_wrap_iter(self, s
: &'a
str) -> IntoWrapIter
<'a
, S
> {
485 let wrap_iter_impl
= WrapIterImpl
::new(&self, s
);
489 wrap_iter_impl
: wrap_iter_impl
,
495 /// An iterator over the lines of the input string which owns a
496 /// `Wrapper`. An instance of `IntoWrapIter` is typically obtained
497 /// through either [`wrap_iter`] or [`Wrapper::into_wrap_iter`].
499 /// Each call of `.next()` method yields a line wrapped in `Some` if the
500 /// input hasn't been fully processed yet. Otherwise it returns `None`.
502 /// [`wrap_iter`]: fn.wrap_iter.html
503 /// [`Wrapper::into_wrap_iter`]: struct.Wrapper.html#method.into_wrap_iter
504 pub struct IntoWrapIter
<'a
, S
: WordSplitter
> {
505 wrapper
: Wrapper
<'a
, S
>,
506 wrap_iter_impl
: WrapIterImpl
<'a
>,
509 impl<'a
, S
: WordSplitter
> Iterator
for IntoWrapIter
<'a
, S
> {
510 type Item
= Cow
<'a
, str>;
512 fn next(&mut self) -> Option
<Cow
<'a
, str>> {
513 self.wrap_iter_impl
.impl_next(&self.wrapper
)
517 /// An iterator over the lines of the input string which borrows a
518 /// `Wrapper`. An instance of `WrapIter` is typically obtained
519 /// through the [`Wrapper::wrap_iter`] method.
521 /// Each call of `.next()` method yields a line wrapped in `Some` if the
522 /// input hasn't been fully processed yet. Otherwise it returns `None`.
524 /// [`Wrapper::wrap_iter`]: struct.Wrapper.html#method.wrap_iter
525 pub struct WrapIter
<'w
, 'a
: 'w
, S
: WordSplitter
+ 'w
> {
526 wrapper
: &'w Wrapper
<'a
, S
>,
527 wrap_iter_impl
: WrapIterImpl
<'a
>,
530 impl<'w
, 'a
: 'w
, S
: WordSplitter
> Iterator
for WrapIter
<'w
, 'a
, S
> {
531 type Item
= Cow
<'a
, str>;
533 fn next(&mut self) -> Option
<Cow
<'a
, str>> {
534 self.wrap_iter_impl
.impl_next(self.wrapper
)
538 struct WrapIterImpl
<'a
> {
541 // CharIndices iterator over self.source.
542 char_indices
: CharIndices
<'a
>,
543 // Is the next element the first one ever produced?
545 // Byte index where the current line starts.
547 // Byte index of the last place where the string can be split.
549 // Size in bytes of the character at self.source[self.split].
551 // Width of self.source[self.start..idx].
553 // Width of self.source[self.start..self.split].
554 line_width_at_split
: usize,
555 // Tracking runs of whitespace characters.
557 // Has iterator finished producing elements?
561 impl<'a
> WrapIterImpl
<'a
> {
562 fn new
<S
: WordSplitter
>(wrapper
: &Wrapper
<'a
, S
>, s
: &'a
str) -> WrapIterImpl
<'a
> {
565 char_indices
: s
.char_indices(),
570 line_width
: wrapper
.initial_indent
.width(),
571 line_width_at_split
: wrapper
.initial_indent
.width(),
572 in_whitespace
: false,
577 fn create_result_line
<S
: WordSplitter
>(&mut self, wrapper
: &Wrapper
<'a
, S
>) -> Cow
<'a
, str> {
578 if self.is_next_first
{
579 self.is_next_first
= false;
580 Cow
::from(wrapper
.initial_indent
)
582 Cow
::from(wrapper
.subsequent_indent
)
586 fn impl_next
<S
: WordSplitter
>(&mut self, wrapper
: &Wrapper
<'a
, S
>) -> Option
<Cow
<'a
, str>> {
591 while let Some((idx
, ch
)) = self.char_indices
.next() {
592 let char_width
= ch
.width().unwrap_or(0);
593 let char_len
= ch
.len_utf8();
594 if ch
.is_whitespace() && ch
!= NBSP
{
595 // Extend the previous split or create a new one.
596 if self.in_whitespace
{
597 self.split_len
+= char_len
;
600 self.split_len
= char_len
;
602 self.line_width_at_split
= self.line_width
+ char_width
;
603 self.in_whitespace
= true;
604 } else if self.line_width
+ char_width
> wrapper
.width
{
605 // There is no room for this character on the current
606 // line. Try to split the final word.
607 let remaining_text
= &self.source
[self.split
+ self.split_len
..];
608 let final_word
= match remaining_text
609 .find(|ch
: char| ch
.is_whitespace() && ch
!= NBSP
) {
610 Some(i
) => &remaining_text
[..i
],
611 None
=> remaining_text
,
615 let splits
= wrapper
.splitter
.split(final_word
);
616 for &(head
, hyp
, _
) in splits
.iter().rev() {
617 if self.line_width_at_split
+ head
.width() + hyp
.width() <= wrapper
.width
{
618 self.split
+= head
.len();
625 if self.start
>= self.split
{
626 // The word is too big to fit on a single line, so we
627 // need to split it at the current index.
628 if wrapper
.break_words
{
629 // Break work at current index.
632 self.line_width_at_split
= self.line_width
;
634 // Add smallest split.
635 self.split
= self.start
+ splits
[0].0.len();
637 self.line_width_at_split
= self.line_width
;
641 if self.start
< self.split
{
642 let mut result_line
= self.create_result_line(wrapper
);
643 cow_add_assign(&mut result_line
, &self.source
[self.start
..self.split
]);
644 cow_add_assign(&mut result_line
, hyphen
);
646 self.start
= self.split
+ self.split_len
;
647 self.line_width
+= wrapper
.subsequent_indent
.width();
648 self.line_width
-= self.line_width_at_split
;
649 self.line_width
+= char_width
;
651 return Some(result_line
);
654 self.in_whitespace
= false;
656 self.line_width
+= char_width
;
660 let final_line
= if self.start
< self.source
.len() {
661 let mut result_line
= self.create_result_line(wrapper
);
662 cow_add_assign(&mut result_line
, &self.source
[self.start
..]);
669 self.finished
= true;
676 /// Return the current terminal width. If the terminal width cannot be
677 /// determined (typically because the standard output is not connected
678 /// to a terminal), a default width of 80 characters will be used.
682 /// Create a `Wrapper` for the current terminal with a two column
686 /// use textwrap::{Wrapper, NoHyphenation, termwidth};
688 /// let width = termwidth() - 4; // Two columns on each side.
689 /// let wrapper = Wrapper::with_splitter(width, NoHyphenation)
690 /// .initial_indent(" ")
691 /// .subsequent_indent(" ");
693 pub fn termwidth() -> usize {
694 term_size
::dimensions_stdout().map_or(80, |(w
, _
)| w
)
697 /// Fill a line of text at `width` characters. Strings are wrapped
698 /// based on their displayed width, not their size in bytes.
700 /// The result is a string with newlines between each line. Use
701 /// [`wrap`] if you need access to the individual lines or
702 /// [`wrap_iter`] for its iterator counterpart.
705 /// use textwrap::fill;
707 /// assert_eq!(fill("Memory safety without garbage collection.", 15),
708 /// "Memory safety\nwithout garbage\ncollection.");
711 /// This function creates a Wrapper on the fly with default settings.
712 /// If you need to set a language corpus for automatic hyphenation, or
713 /// need to fill many strings, then it is suggested to create Wrapper
714 /// and call its [`fill` method].
716 /// [`wrap`]: fn.wrap.html
717 /// [`wrap_iter`]: fn.wrap_iter.html
718 /// [`fill` method]: struct.Wrapper.html#method.fill
719 pub fn fill(s
: &str, width
: usize) -> String
{
720 Wrapper
::new(width
).fill(s
)
723 /// Wrap a line of text at `width` characters. Strings are wrapped
724 /// based on their displayed width, not their size in bytes.
726 /// This function creates a Wrapper on the fly with default settings.
727 /// If you need to set a language corpus for automatic hyphenation, or
728 /// need to wrap many strings, then it is suggested to create Wrapper
729 /// and call its [`wrap` method].
731 /// The result is a vector of strings. Use [`wrap_iter`] if you need an
732 /// iterator version.
737 /// use textwrap::wrap;
739 /// assert_eq!(wrap("Concurrency without data races.", 15),
740 /// vec!["Concurrency",
744 /// assert_eq!(wrap("Concurrency without data races.", 20),
745 /// vec!["Concurrency without",
749 /// [`wrap_iter`]: fn.wrap_iter.html
750 /// [`wrap` method]: struct.Wrapper.html#method.wrap
751 pub fn wrap(s
: &str, width
: usize) -> Vec
<Cow
<str>> {
752 Wrapper
::new(width
).wrap(s
)
755 /// Lazily wrap a line of text at `self.width` characters. Strings are
756 /// wrapped based on their displayed width, not their size in bytes.
758 /// This function creates a Wrapper on the fly with default settings.
759 /// It then calls the [`into_wrap_iter`] method. Hence, the return
760 /// value is an [`IntoWrapIter`], not a [`WrapIter`] as the function
761 /// name would otherwise suggest.
763 /// If you need to set a language corpus for automatic hyphenation, or
764 /// need to wrap many strings, then it is suggested to create Wrapper
765 /// and call its [`wrap_iter`] or [`into_wrap_iter`] methods.
770 /// use std::borrow::Cow;
771 /// use textwrap::wrap_iter;
773 /// let mut wrap20_iter = wrap_iter("Zero-cost abstractions.", 20);
774 /// assert_eq!(wrap20_iter.next(), Some(Cow::from("Zero-cost")));
775 /// assert_eq!(wrap20_iter.next(), Some(Cow::from("abstractions.")));
776 /// assert_eq!(wrap20_iter.next(), None);
778 /// let mut wrap25_iter = wrap_iter("Zero-cost abstractions.", 25);
779 /// assert_eq!(wrap25_iter.next(), Some(Cow::from("Zero-cost abstractions.")));
780 /// assert_eq!(wrap25_iter.next(), None);
783 /// [`wrap_iter`]: struct.Wrapper.html#method.wrap_iter
784 /// [`into_wrap_iter`]: struct.Wrapper.html#method.into_wrap_iter
785 /// [`IntoWrapIter`]: struct.IntoWrapIter.html
786 /// [`WrapIter`]: struct.WrapIter.html
787 pub fn wrap_iter
<'s
>(s
: &'s
str, width
: usize) -> IntoWrapIter
<'s
, HyphenSplitter
> {
788 Wrapper
::new(width
).into_wrap_iter(s
)
791 /// Add prefix to each non-empty line.
794 /// use textwrap::indent;
796 /// assert_eq!(indent("Foo\nBar\n", " "), " Foo\n Bar\n");
799 /// Empty lines (lines consisting only of whitespace) are not indented
800 /// and the whitespace is replaced by a single newline (`\n`):
803 /// use textwrap::indent;
805 /// assert_eq!(indent("Foo\n\nBar\n \t \nBaz\n", " "),
806 /// " Foo\n\n Bar\n\n Baz\n");
809 /// Leading and trailing whitespace on non-empty lines is kept
813 /// use textwrap::indent;
815 /// assert_eq!(indent(" \t Foo ", " "), " \t Foo \n");
817 pub fn indent(s
: &str, prefix
: &str) -> String
{
818 let mut result
= String
::new();
819 for line
in s
.lines() {
820 if line
.chars().any(|c
| !c
.is_whitespace()) {
821 result
.push_str(prefix
);
822 result
.push_str(line
);
829 /// Removes common leading whitespace from each line.
831 /// This will look at each non-empty line and determine the maximum
832 /// amount of whitespace that can be removed from the line.
835 /// use textwrap::dedent;
837 /// assert_eq!(dedent(" 1st line\n 2nd line\n"),
838 /// "1st line\n2nd line\n");
840 pub fn dedent(s
: &str) -> String
{
841 let mut prefix
= String
::new();
842 let mut lines
= s
.lines();
844 // We first search for a non-empty line to find a prefix.
845 for line
in &mut lines
{
846 let whitespace
= line
.chars()
847 .take_while(|c
| c
.is_whitespace())
848 .collect
::<String
>();
849 // Check if the line had anything but whitespace
850 if whitespace
.len() < line
.len() {
856 // We then continue looking through the remaining lines to
857 // possibly shorten the prefix.
858 for line
in &mut lines
{
859 let whitespace
= line
.chars()
861 .take_while(|&(a
, b
)| a
== b
)
863 .collect
::<String
>();
864 // Check if we have found a shorter prefix
865 if whitespace
.len() < prefix
.len() {
870 // We now go over the lines a second time to build the result.
871 let mut result
= String
::new();
872 for line
in s
.lines() {
873 if line
.starts_with(&prefix
) && line
.chars().any(|c
| !c
.is_whitespace()) {
874 let (_
, tail
) = line
.split_at(prefix
.len());
875 result
.push_str(tail
);
884 #[cfg(feature = "hyphenation")]
885 extern crate hyphenation
;
887 #[cfg(feature = "hyphenation")]
888 use hyphenation
::Language
;
891 /// Add newlines. Ensures that the final line in the vector also
893 fn add_nl(lines
: &Vec
<&str>) -> String
{
894 lines
.join("\n") + "\n"
899 assert_eq
!(wrap("foo", 10), vec
!["foo"]);
904 assert_eq
!(wrap("foo bar baz", 5), vec
!["foo", "bar", "baz"]);
908 fn multi_word_on_line() {
909 assert_eq
!(wrap("foo bar baz", 10), vec
!["foo bar", "baz"]);
914 assert_eq
!(wrap("foo", 0), vec
!["f", "o", "o"]);
919 assert_eq
!(wrap("foo bar", 0), vec
!["f", "o", "o", "b", "a", "r"]);
923 fn leading_whitespace() {
924 assert_eq
!(wrap(" foo bar", 6), vec
![" foo", "bar"]);
928 fn trailing_whitespace() {
929 assert_eq
!(wrap("foo bar ", 6), vec
!["foo", "bar "]);
933 fn interior_whitespace() {
934 assert_eq
!(wrap("foo: bar baz", 10), vec
!["foo: bar", "baz"]);
938 fn extra_whitespace_start_of_line() {
939 // Whitespace is only significant inside a line. After a line
940 // gets too long and is broken, the first word starts in
941 // column zero and is not indented. The line before might end
942 // up with trailing whitespace.
943 assert_eq
!(wrap("foo bar", 5), vec
!["foo", "bar"]);
947 fn wide_character_handling() {
948 assert_eq
!(wrap("Hello, World!", 15), vec
!["Hello, World!"]);
949 assert_eq
!(wrap("Hello, World!", 15),
950 vec
!["Hello,", "World!"]);
955 let wrapper
= Wrapper
::new(10).initial_indent("!!!");
956 assert_eq
!(wrapper
.fill(""), "");
960 fn indent_single_line() {
961 let wrapper
= Wrapper
::new(10).initial_indent(">>>"); // No trailing space
962 assert_eq
!(wrapper
.fill("foo"), ">>>foo");
966 fn indent_multiple_lines() {
967 let wrapper
= Wrapper
::new(6).initial_indent("* ").subsequent_indent(" ");
968 assert_eq
!(wrapper
.wrap("foo bar baz"), vec
!["* foo", " bar", " baz"]);
972 fn indent_break_words() {
973 let wrapper
= Wrapper
::new(5).initial_indent("* ").subsequent_indent(" ");
974 assert_eq
!(wrapper
.wrap("foobarbaz"), vec
!["* foo", " bar", " baz"]);
979 assert_eq
!(wrap("foo-bar", 5), vec
!["foo-", "bar"]);
983 fn trailing_hyphen() {
984 let wrapper
= Wrapper
::new(5).break_words(false);
985 assert_eq
!(wrapper
.wrap("foobar-"), vec
!["foobar-"]);
989 fn multiple_hyphens() {
990 assert_eq
!(wrap("foo-bar-baz", 5), vec
!["foo-", "bar-", "baz"]);
995 let wrapper
= Wrapper
::new(5).break_words(false);
996 assert_eq
!(wrapper
.wrap("The --foo-bar flag."),
997 vec
!["The", "--foo-", "bar", "flag."]);
1001 fn repeated_hyphens() {
1002 let wrapper
= Wrapper
::new(4).break_words(false);
1003 assert_eq
!(wrapper
.wrap("foo--bar"), vec
!["foo--bar"]);
1007 fn hyphens_alphanumeric() {
1008 assert_eq
!(wrap("Na2-CH4", 5), vec
!["Na2-", "CH4"]);
1012 fn hyphens_non_alphanumeric() {
1013 let wrapper
= Wrapper
::new(5).break_words(false);
1014 assert_eq
!(wrapper
.wrap("foo(-)bar"), vec
!["foo(-)bar"]);
1018 fn multiple_splits() {
1019 assert_eq
!(wrap("foo-bar-baz", 9), vec
!["foo-bar-", "baz"]);
1024 let wrapper
= Wrapper
::new(5).break_words(false);
1025 assert_eq
!(wrapper
.wrap("foobar-baz"), vec
!["foobar-", "baz"]);
1029 fn no_hyphenation() {
1030 let wrapper
= Wrapper
::with_splitter(8, NoHyphenation
);
1031 assert_eq
!(wrapper
.wrap("foo bar-baz"), vec
!["foo", "bar-baz"]);
1035 #[cfg(feature = "hyphenation")]
1036 fn auto_hyphenation() {
1037 let corpus
= hyphenation
::load(Language
::English_US
).unwrap();
1038 let wrapper
= Wrapper
::new(10);
1039 assert_eq
!(wrapper
.wrap("Internationalization"),
1040 vec
!["Internatio", "nalization"]);
1042 let wrapper
= Wrapper
::with_splitter(10, corpus
);
1043 assert_eq
!(wrapper
.wrap("Internationalization"),
1044 vec
!["Interna-", "tionaliza-", "tion"]);
1048 #[cfg(feature = "hyphenation")]
1049 fn borrowed_lines() {
1050 // Lines that end with an extra hyphen are owned, the final
1051 // line is borrowed.
1052 use std
::borrow
::Cow
::{Borrowed, Owned}
;
1053 let corpus
= hyphenation
::load(Language
::English_US
).unwrap();
1054 let wrapper
= Wrapper
::with_splitter(10, corpus
);
1055 let lines
= wrapper
.wrap("Internationalization");
1056 if let Borrowed(s
) = lines
[0] {
1057 assert
!(false, "should not have been borrowed: {:?}", s
);
1059 if let Borrowed(s
) = lines
[1] {
1060 assert
!(false, "should not have been borrowed: {:?}", s
);
1062 if let Owned(ref s
) = lines
[2] {
1063 assert
!(false, "should not have been owned: {:?}", s
);
1068 #[cfg(feature = "hyphenation")]
1069 fn auto_hyphenation_with_hyphen() {
1070 let corpus
= hyphenation
::load(Language
::English_US
).unwrap();
1071 let wrapper
= Wrapper
::new(8).break_words(false);
1072 assert_eq
!(wrapper
.wrap("over-caffinated"), vec
!["over-", "caffinated"]);
1074 let wrapper
= Wrapper
::with_splitter(8, corpus
).break_words(false);
1075 assert_eq
!(wrapper
.wrap("over-caffinated"),
1076 vec
!["over-", "caffi-", "nated"]);
1081 assert_eq
!(wrap("foobarbaz", 3), vec
!["foo", "bar", "baz"]);
1085 fn break_words_wide_characters() {
1086 assert_eq
!(wrap("Hello", 5), vec
!["He", "ll", "o"]);
1090 fn break_words_zero_width() {
1091 assert_eq
!(wrap("foobar", 0), vec
!["f", "o", "o", "b", "a", "r"]);
1095 fn test_non_breaking_space() {
1096 let wrapper
= Wrapper
::new(5).break_words(false);
1097 assert_eq
!(wrapper
.fill("foo bar baz"), "foo bar baz");
1101 fn test_non_breaking_hyphen() {
1102 let wrapper
= Wrapper
::new(5).break_words(false);
1103 assert_eq
!(wrapper
.fill("foo‑bar‑baz"), "foo‑bar‑baz");
1108 assert_eq
!(fill("foo bar baz", 10), "foo bar\nbaz");
1112 fn test_indent_empty() {
1113 assert_eq
!(indent("\n", " "), "\n");
1117 #[cfg_attr(rustfmt, rustfmt_skip)]
1118 fn test_indent_nonempty() {
1119 let x
= vec
![" foo",
1122 let y
= vec
!["// foo",
1125 assert_eq
!(indent(&add_nl(&x
), "//"), add_nl(&y
));
1129 #[cfg_attr(rustfmt, rustfmt_skip)]
1130 fn test_indent_empty_line() {
1131 let x
= vec
![" foo",
1135 let y
= vec
!["// foo",
1139 assert_eq
!(indent(&add_nl(&x
), "//"), add_nl(&y
));
1143 fn test_dedent_empty() {
1144 assert_eq
!(dedent(""), "");
1148 #[cfg_attr(rustfmt, rustfmt_skip)]
1149 fn test_dedent_multi_line() {
1150 let x
= vec
![" foo",
1153 let y
= vec
![" foo",
1156 assert_eq
!(dedent(&add_nl(&x
)), add_nl(&y
));
1160 #[cfg_attr(rustfmt, rustfmt_skip)]
1161 fn test_dedent_empty_line() {
1162 let x
= vec
![" foo",
1166 let y
= vec
![" foo",
1170 assert_eq
!(dedent(&add_nl(&x
)), add_nl(&y
));
1174 #[cfg_attr(rustfmt, rustfmt_skip)]
1175 fn test_dedent_mixed_whitespace() {
1176 let x
= vec
!["\tfoo",
1178 let y
= vec
!["\tfoo",
1180 assert_eq
!(dedent(&add_nl(&x
)), add_nl(&y
));