1 //! Functions for filling text.
2
3 use crate::{wrap, wrap_algorithms, Options, WordSeparator};
4
5 /// Fill a line of text at a given width.
6 ///
7 /// The result is a [`String`], complete with newlines between each
8 /// line. Use [`wrap()`] if you need access to the individual lines.
9 ///
10 /// The easiest way to use this function is to pass an integer for
11 /// `width_or_options`:
12 ///
13 /// ```
14 /// use textwrap::fill;
15 ///
16 /// assert_eq!(
17 /// fill("Memory safety without garbage collection.", 15),
18 /// "Memory safety\nwithout garbage\ncollection."
19 /// );
20 /// ```
21 ///
22 /// If you need to customize the wrapping, you can pass an [`Options`]
23 /// instead of an `usize`:
24 ///
25 /// ```
26 /// use textwrap::{fill, Options};
27 ///
28 /// let options = Options::new(15)
29 /// .initial_indent("- ")
30 /// .subsequent_indent(" ");
31 /// assert_eq!(
32 /// fill("Memory safety without garbage collection.", &options),
33 /// "- Memory safety\n without\n garbage\n collection."
34 /// );
35 /// ```
fill<'a, Opt>(text: &str, width_or_options: Opt) -> String where Opt: Into<Options<'a>>,36 pub fn fill<'a, Opt>(text: &str, width_or_options: Opt) -> String
37 where
38 Opt: Into<Options<'a>>,
39 {
40 let options = width_or_options.into();
41
42 if text.len() < options.width && !text.contains('\n') && options.initial_indent.is_empty() {
43 String::from(text.trim_end_matches(' '))
44 } else {
45 fill_slow_path(text, options)
46 }
47 }
48
49 /// Slow path for fill.
50 ///
51 /// This is taken when `text` is longer than `options.width`.
fill_slow_path(text: &str, options: Options<'_>) -> String52 pub(crate) fn fill_slow_path(text: &str, options: Options<'_>) -> String {
53 // This will avoid reallocation in simple cases (no
54 // indentation, no hyphenation).
55 let mut result = String::with_capacity(text.len());
56
57 let line_ending_str = options.line_ending.as_str();
58 for (i, line) in wrap(text, options).iter().enumerate() {
59 if i > 0 {
60 result.push_str(line_ending_str);
61 }
62 result.push_str(line);
63 }
64
65 result
66 }
67
68 /// Fill `text` in-place without reallocating the input string.
69 ///
70 /// This function works by modifying the input string: some `' '`
71 /// characters will be replaced by `'\n'` characters. The rest of the
72 /// text remains untouched.
73 ///
74 /// Since we can only replace existing whitespace in the input with
75 /// `'\n'` (there is no space for `"\r\n"`), we cannot do hyphenation
76 /// nor can we split words longer than the line width. We also need to
77 /// use `AsciiSpace` as the word separator since we need `' '`
78 /// characters between words in order to replace some of them with a
79 /// `'\n'`. Indentation is also ruled out. In other words,
80 /// `fill_inplace(width)` behaves as if you had called [`fill()`] with
81 /// these options:
82 ///
83 /// ```
84 /// # use textwrap::{core, LineEnding, Options, WordSplitter, WordSeparator, WrapAlgorithm};
85 /// # let width = 80;
86 /// Options::new(width)
87 /// .break_words(false)
88 /// .line_ending(LineEnding::LF)
89 /// .word_separator(WordSeparator::AsciiSpace)
90 /// .wrap_algorithm(WrapAlgorithm::FirstFit)
91 /// .word_splitter(WordSplitter::NoHyphenation);
92 /// ```
93 ///
94 /// The wrap algorithm is
95 /// [`WrapAlgorithm::FirstFit`](crate::WrapAlgorithm::FirstFit) since
96 /// this is the fastest algorithm — and the main reason to use
97 /// `fill_inplace` is to get the string broken into newlines as fast
98 /// as possible.
99 ///
100 /// A last difference is that (unlike [`fill()`]) `fill_inplace` can
101 /// leave trailing whitespace on lines. This is because we wrap by
102 /// inserting a `'\n'` at the final whitespace in the input string:
103 ///
104 /// ```
105 /// let mut text = String::from("Hello World!");
106 /// textwrap::fill_inplace(&mut text, 10);
107 /// assert_eq!(text, "Hello \nWorld!");
108 /// ```
109 ///
110 /// If we didn't do this, the word `World!` would end up being
111 /// indented. You can avoid this if you make sure that your input text
112 /// has no double spaces.
113 ///
114 /// # Performance
115 ///
116 /// In benchmarks, `fill_inplace` is about twice as fast as
117 /// [`fill()`]. Please see the [`linear`
118 /// benchmark](https://github.com/mgeisler/textwrap/blob/master/benchmarks/linear.rs)
119 /// for details.
fill_inplace(text: &mut String, width: usize)120 pub fn fill_inplace(text: &mut String, width: usize) {
121 let mut indices = Vec::new();
122
123 let mut offset = 0;
124 for line in text.split('\n') {
125 let words = WordSeparator::AsciiSpace
126 .find_words(line)
127 .collect::<Vec<_>>();
128 let wrapped_words = wrap_algorithms::wrap_first_fit(&words, &[width as f64]);
129
130 let mut line_offset = offset;
131 for words in &wrapped_words[..wrapped_words.len() - 1] {
132 let line_len = words
133 .iter()
134 .map(|word| word.len() + word.whitespace.len())
135 .sum::<usize>();
136
137 line_offset += line_len;
138 // We've advanced past all ' ' characters -- want to move
139 // one ' ' backwards and insert our '\n' there.
140 indices.push(line_offset - 1);
141 }
142
143 // Advance past entire line, plus the '\n' which was removed
144 // by the split call above.
145 offset += line.len() + 1;
146 }
147
148 let mut bytes = std::mem::take(text).into_bytes();
149 for idx in indices {
150 bytes[idx] = b'\n';
151 }
152 *text = String::from_utf8(bytes).unwrap();
153 }
154
155 #[cfg(test)]
156 mod tests {
157 use super::*;
158 use crate::WrapAlgorithm;
159
160 #[test]
fill_simple()161 fn fill_simple() {
162 assert_eq!(fill("foo bar baz", 10), "foo bar\nbaz");
163 }
164
165 #[test]
fill_unicode_boundary()166 fn fill_unicode_boundary() {
167 // https://github.com/mgeisler/textwrap/issues/390
168 fill("\u{1b}!Ͽ", 10);
169 }
170
171 #[test]
non_breaking_space()172 fn non_breaking_space() {
173 let options = Options::new(5).break_words(false);
174 assert_eq!(fill("foo bar baz", &options), "foo bar baz");
175 }
176
177 #[test]
non_breaking_hyphen()178 fn non_breaking_hyphen() {
179 let options = Options::new(5).break_words(false);
180 assert_eq!(fill("foo‑bar‑baz", &options), "foo‑bar‑baz");
181 }
182
183 #[test]
fill_preserves_line_breaks_trims_whitespace()184 fn fill_preserves_line_breaks_trims_whitespace() {
185 assert_eq!(fill(" ", 80), "");
186 assert_eq!(fill(" \n ", 80), "\n");
187 assert_eq!(fill(" \n \n \n ", 80), "\n\n\n");
188 }
189
190 #[test]
preserve_line_breaks()191 fn preserve_line_breaks() {
192 assert_eq!(fill("", 80), "");
193 assert_eq!(fill("\n", 80), "\n");
194 assert_eq!(fill("\n\n\n", 80), "\n\n\n");
195 assert_eq!(fill("test\n", 80), "test\n");
196 assert_eq!(fill("test\n\na\n\n", 80), "test\n\na\n\n");
197 assert_eq!(
198 fill(
199 "1 3 5 7\n1 3 5 7",
200 Options::new(7).wrap_algorithm(WrapAlgorithm::FirstFit)
201 ),
202 "1 3 5 7\n1 3 5 7"
203 );
204 assert_eq!(
205 fill(
206 "1 3 5 7\n1 3 5 7",
207 Options::new(5).wrap_algorithm(WrapAlgorithm::FirstFit)
208 ),
209 "1 3 5\n7\n1 3 5\n7"
210 );
211 }
212
213 #[test]
break_words_line_breaks()214 fn break_words_line_breaks() {
215 assert_eq!(fill("ab\ncdefghijkl", 5), "ab\ncdefg\nhijkl");
216 assert_eq!(fill("abcdefgh\nijkl", 5), "abcde\nfgh\nijkl");
217 }
218
219 #[test]
break_words_empty_lines()220 fn break_words_empty_lines() {
221 assert_eq!(
222 fill("foo\nbar", &Options::new(2).break_words(false)),
223 "foo\nbar"
224 );
225 }
226
227 #[test]
fill_inplace_empty()228 fn fill_inplace_empty() {
229 let mut text = String::from("");
230 fill_inplace(&mut text, 80);
231 assert_eq!(text, "");
232 }
233
234 #[test]
fill_inplace_simple()235 fn fill_inplace_simple() {
236 let mut text = String::from("foo bar baz");
237 fill_inplace(&mut text, 10);
238 assert_eq!(text, "foo bar\nbaz");
239 }
240
241 #[test]
fill_inplace_multiple_lines()242 fn fill_inplace_multiple_lines() {
243 let mut text = String::from("Some text to wrap over multiple lines");
244 fill_inplace(&mut text, 12);
245 assert_eq!(text, "Some text to\nwrap over\nmultiple\nlines");
246 }
247
248 #[test]
fill_inplace_long_word()249 fn fill_inplace_long_word() {
250 let mut text = String::from("Internationalization is hard");
251 fill_inplace(&mut text, 10);
252 assert_eq!(text, "Internationalization\nis hard");
253 }
254
255 #[test]
fill_inplace_no_hyphen_splitting()256 fn fill_inplace_no_hyphen_splitting() {
257 let mut text = String::from("A well-chosen example");
258 fill_inplace(&mut text, 10);
259 assert_eq!(text, "A\nwell-chosen\nexample");
260 }
261
262 #[test]
fill_inplace_newlines()263 fn fill_inplace_newlines() {
264 let mut text = String::from("foo bar\n\nbaz\n\n\n");
265 fill_inplace(&mut text, 10);
266 assert_eq!(text, "foo bar\n\nbaz\n\n\n");
267 }
268
269 #[test]
fill_inplace_newlines_reset_line_width()270 fn fill_inplace_newlines_reset_line_width() {
271 let mut text = String::from("1 3 5\n1 3 5 7 9\n1 3 5 7 9 1 3");
272 fill_inplace(&mut text, 10);
273 assert_eq!(text, "1 3 5\n1 3 5 7 9\n1 3 5 7 9\n1 3");
274 }
275
276 #[test]
fill_inplace_leading_whitespace()277 fn fill_inplace_leading_whitespace() {
278 let mut text = String::from(" foo bar baz");
279 fill_inplace(&mut text, 10);
280 assert_eq!(text, " foo bar\nbaz");
281 }
282
283 #[test]
fill_inplace_trailing_whitespace()284 fn fill_inplace_trailing_whitespace() {
285 let mut text = String::from("foo bar baz ");
286 fill_inplace(&mut text, 10);
287 assert_eq!(text, "foo bar\nbaz ");
288 }
289
290 #[test]
fill_inplace_interior_whitespace()291 fn fill_inplace_interior_whitespace() {
292 // To avoid an unwanted indentation of "baz", it is important
293 // to replace the final ' ' with '\n'.
294 let mut text = String::from("foo bar baz");
295 fill_inplace(&mut text, 10);
296 assert_eq!(text, "foo bar \nbaz");
297 }
298 }
299