v0.21.5

Compare Source

• Add Debug and Clone impls for the general purpose Engine

v1.10.2

Compare Source

===================
This is a new patch release that fixes a search regression where incorrect
matches could be reported.

Bug fixes:

• BUG #​1110:
  Revert broadening of reverse suffix literal optimization introduced in 1.10.1.

v1.10.1

Compare Source

===================
This is a new patch release with a minor increase in the number of valid
patterns and a broadening of some literal optimizations.

New features:

• FEATURE 04f5d7be:
  Loosen ASCII-compatible rules such that regexes like (?-u:☃) are now allowed.

Performance improvements:

• PERF 8a8d599f:
  Broader the reverse suffix optimization to apply in more cases.

v1.10.0

Compare Source

===================
This is a new minor release of regex that adds support for start and end
word boundary assertions. That is, \< and \>. The minimum supported Rust
version has also been raised to 1.65, which was released about one year ago.

The new word boundary assertions are:

• \< or \b{start}: a Unicode start-of-word boundary (\W|\A on the left,
  \w on the right).
• \> or \b{end}: a Unicode end-of-word boundary (\w on the left, \W|\z
  on the right)).
• \b{start-half}: half of a Unicode start-of-word boundary (\W|\A on the
  left).
• \b{end-half}: half of a Unicode end-of-word boundary (\W|\z on the
  right).

The \< and \> are GNU extensions to POSIX regexes. They have been added
to the regex crate because they enjoy somewhat broad support in other regex
engines as well (for example, vim). The \b{start} and \b{end} assertions
are aliases for \< and \>, respectively.

The \b{start-half} and \b{end-half} assertions are not found in any
other regex engine (although regex engines with general look-around support
can certainly express them). They were added principally to support the
implementation of word matching in grep programs, where one generally wants to
be a bit more flexible in what is considered a word boundary.

New features:

• FEATURE #​469:
  Add support for \< and \> word boundary assertions.
• FEATURE(regex-automata) #​1031:
  DFAs now have a start_state method that doesn't use an Input.

Performance improvements:

• PERF #​1051:
  Unicode character class operations have been optimized in regex-syntax.
• PERF #​1090:
  Make patterns containing lots of literal characters use less memory.

Bug fixes:

• BUG #​1046:
  Fix a bug that could result in incorrect match spans when using a Unicode word
  boundary and searching non-ASCII strings.
• BUG(regex-syntax) #​1047:
  Fix panics that can occur in Ast->Hir translation (not reachable from regex
  crate).
• BUG(regex-syntax) #​1088:
  Remove guarantees in the API that connect the u flag with a specific HIR
  representation.

regex-automata breaking change release:

This release includes a regex-automata 0.4.0 breaking change release, which
was necessary in order to support the new word boundary assertions. For
example, the Look enum has new variants and the LookSet type now uses u32
instead of u16 to represent a bitset of look-around assertions. These are
overall very minor changes, and most users of regex-automata should be able
to move to 0.4 from 0.3 without any changes at all.

regex-syntax breaking change release:

This release also includes a regex-syntax 0.8.0 breaking change release,
which, like regex-automata, was necessary in order to support the new word
boundary assertions. This release also includes some changes to the Ast
type to reduce heap usage in some cases. If you are using the Ast type
directly, your code may require some minor modifications. Otherwise, users of
regex-syntax 0.7 should be able to migrate to 0.8 without any code changes.

regex-lite release:

The regex-lite 0.1.1 release contains support for the new word boundary
assertions. There are no breaking changes.

v1.9.6

Compare Source

==================
This is a patch release that fixes a panic that can occur when the default
regex size limit is increased to a large number.

• BUG aa4e4c71:
  Fix a bug where computing the maximum haystack length for the bounded
  backtracker could result underflow and thus provoke a panic later in a search
  due to a broken invariant.

v1.9.5

Compare Source

==================
This is a patch release that hopefully mostly fixes a performance bug that
occurs when sharing a regex across multiple threads.

Issue #​934
explains this in more detail. It is also noted in the crate
documentation.
The bug can appear when sharing a regex across multiple threads simultaneously,
as might be the case when using a regex from a OnceLock, lazy_static or
similar primitive. Usually high contention only results when using many threads
to execute searches on small haystacks.

One can avoid the contention problem entirely through one of two methods.
The first is to use lower level APIs from regex-automata that require passing
state explicitly, such as meta::Regex::search_with.
The second is to clone a regex and send it to other threads explicitly. This
will not use any additional memory usage compared to sharing the regex. The
only downside of this approach is that it may be less convenient, for example,
it won't work with things like OnceLock or lazy_static or once_cell.

With that said, as of this release, the contention performance problems have
been greatly reduced. This was achieved by changing the free-list so that it
was sharded across threads, and that ensuring each sharded mutex occupies a
single cache line to mitigate false sharing. So while contention may still
impact performance in some cases, it should be a lot better now.

Because of the changes to how the free-list works, please report any issues you
find with this release. That not only includes search time regressions but also
significant regressions in memory usage. Reporting improvements is also welcome
as well! If possible, provide a reproduction.

Bug fixes:

• BUG #​934:
  Fix a performance bug where high contention on a single regex led to massive
  slow downs.

v1.9.4

Compare Source

==================
This is a patch release that fixes a bug where RegexSet::is_match(..) could
incorrectly return false (even when RegexSet::matches(..).matched_any()
returns true).

Bug fixes:

• BUG #​1070:
  Fix a bug where a prefilter was incorrectly configured for a RegexSet.

v1.9.3

Compare Source

==================
This is a patch release that fixes a bug where some searches could result in
incorrect match offsets being reported. It is difficult to characterize the
types of regexes susceptible to this bug. They generally involve patterns
that contain no prefix or suffix literals, but have an inner literal along with
a regex prefix that can conditionally match.

Bug fixes:

• BUG #​1060:
  Fix a bug with the reverse inner literal optimization reporting incorrect match
  offsets.

v1.9.2

Compare Source

==================
This is a patch release that fixes another memory usage regression. This
particular regression occurred only when using a RegexSet. In some cases,
much more heap memory (by one or two orders of magnitude) was allocated than in
versions prior to 1.9.0.

Bug fixes:

• BUG #​1059:
  Fix a memory usage regression when using a RegexSet.

v1.9.1

Compare Source

==================
This is a patch release which fixes a memory usage regression. In the regex
1.9 release, one of the internal engines used a more aggressive allocation
strategy than what was done previously. This patch release reverts to the
prior on-demand strategy.

Bug fixes:

• BUG #​1027:
  Change the allocation strategy for the backtracker to be less aggressive.

v1.9.0

Compare Source

==================
This release marks the end of a years long rewrite of the regex crate
internals. Since this is
such a big release, please report any issues or regressions you find. We would
also love to hear about improvements as well.

In addition to many internal improvements that should hopefully result in
"my regex searches are faster," there have also been a few API additions:

• A new Captures::extract method for quickly accessing the substrings
  that match each capture group in a regex.
• A new inline flag, R, which enables CRLF mode. This makes . match any
  Unicode scalar value except for \r and \n, and also makes (?m:^) and
  (?m:$) match after and before both \r and \n, respectively, but never
  between a \r and \n.
• RegexBuilder::line_terminator was added to further customize the line
  terminator used by (?m:^) and (?m:$) to be any arbitrary byte.
• The std Cargo feature is now actually optional. That is, the regex crate
  can be used without the standard library.
• Because regex 1.9 may make binary size and compile times even worse, a
  new experimental crate called regex-lite has been published. It prioritizes
  binary size and compile times over functionality (like Unicode) and
  performance. It shares no code with the regex crate.

New features:

• FEATURE #​244:
  One can opt into CRLF mode via the R flag.
  e.g., (?mR:$) matches just before \r\n.
• FEATURE #​259:
  Multi-pattern searches with offsets can be done with regex-automata 0.3.
• FEATURE #​476:
  std is now an optional feature. regex may be used with only alloc.
• FEATURE #​644:
  RegexBuilder::line_terminator configures how (?m:^) and (?m:$) behave.
• FEATURE #​675:
  Anchored search APIs are now available in regex-automata 0.3.
• FEATURE #​824:
  Add new Captures::extract method for easier capture group access.
• FEATURE #​961:
  Add regex-lite crate with smaller binary sizes and faster compile times.
• FEATURE #​1022:
  Add TryFrom implementations for the Regex type.

Performance improvements:

• PERF #​68:
  Added a one-pass DFA engine for faster capture group matching.
• PERF #​510:
  Inner literals are now used to accelerate searches, e.g., \w+@​\w+ will scan
  for @.
• PERF #​787,
  PERF #​891:
  Makes literal optimizations apply to regexes of the form \b(foo|bar|quux)\b.

(There are many more performance improvements as well, but not all of them have
specific issues devoted to them.)

Bug fixes:

• BUG #​429:
  Fix matching bugs related to \B and inconsistencies across internal engines.
• BUG #​517:
  Fix matching bug with capture groups.
• BUG #​579:
  Fix matching bug with word boundaries.
• BUG #​779:
  Fix bug where some regexes like (re)+ were not equivalent to (re)(re)*.
• BUG #​850:
  Fix matching bug inconsistency between NFA and DFA engines.
• BUG #​921:
  Fix matching bug where literal extraction got confused by $.
• BUG #​976:
  Add documentation to replacement routines about dealing with fallibility.
• BUG #​1002:
  Use corpus rejection in fuzz testing.

v1.8.4

Compare Source

==================
This is a patch release that fixes a bug where (?-u:\B) was allowed in
Unicode regexes, despite the fact that the current matching engines can report
match offsets between the code units of a single UTF-8 encoded codepoint. That
in turn means that match offsets that split a codepoint could be reported,
which in turn results in panicking when one uses them to slice a &str.

This bug occurred in the transition to regex 1.8 because the underlying
syntactical error that prevented this regex from compiling was intentionally
removed. That's because (?-u:\B) will be permitted in Unicode regexes in
regex 1.9, but the matching engines will guarantee to never report match
offsets that split a codepoint. When the underlying syntactical error was
removed, no code was added to ensure that (?-u:\B) didn't compile in the
regex 1.8 transition release. This release, regex 1.8.4, adds that code
such that Regex::new(r"(?-u:\B)") returns to the regex <1.8 behavior of
not compiling. (A bytes::Regex can still of course compile it.)

Bug fixes:

• BUG #​1006:
  Fix a bug where (?-u:\B) was allowed in Unicode regexes, and in turn could
  lead to match offsets that split a codepoint in &str.

v1.8.3

Compare Source

==================
This is a patch release that fixes a bug where the regex would report a
match at every position even when it shouldn't. This could occur in a very
small subset of regexes, usually an alternation of simple literals that
have particular properties. (See the issue linked below for a more precise
description.)

Bug fixes:

• BUG #​999:
  Fix a bug where a match at every position is erroneously reported.

v1.8.2

Compare Source

==================
This is a patch release that fixes a bug where regex compilation could panic
in debug mode for regexes with large counted repetitions. For example,
a{2147483516}{2147483416}{5} resulted in an integer overflow that wrapped
in release mode but panicking in debug mode. Despite the unintended wrapping
arithmetic in release mode, it didn't cause any other logical bugs since the
errant code was for new analysis that wasn't used yet.

Bug fixes:

• BUG #​995:
  Fix a bug where regex compilation with large counted repetitions could panic.

v1.8.1

Compare Source

==================
This is a patch release that fixes a bug where a regex match could be reported
where none was found. Specifically, the bug occurs when a pattern contains some
literal prefixes that could be extracted and an optional word boundary in the
prefix.

Bug fixes:

• BUG #​981:
  Fix a bug where a word boundary could interact with prefix literal
  optimizations and lead to a false positive match.

v1.8.0

Compare Source

==================
This is a sizeable release that will be soon followed by another sizeable
release. Both of them will combined close over 40 existing issues and PRs.

This first release, despite its size, essentially represents preparatory work
for the second release, which will be even bigger. Namely, this release:

• Increases the MSRV to Rust 1.60.0, which was released about 1 year ago.
• Upgrades its dependency on aho-corasick to the recently released 1.0
  version.
• Upgrades its dependency on regex-syntax to the simultaneously released
  0.7 version. The changes to regex-syntax principally revolve around a
  rewrite of its literal extraction code and a number of simplifications and
  optimizations to its high-level intermediate representation (HIR).

The second release, which will follow ~shortly after the release above, will
contain a soup-to-nuts rewrite of every regex engine. This will be done by
bringing regex-automata into
this repository, and then changing the regex crate to be nothing but an API
shim layer on top of regex-automata's API.

These tandem releases are the culmination of about 3
years of on-and-off work that began in earnest in March
2020.

Because of the scale of changes involved in these releases, I would love to
hear about your experience. Especially if you notice undocumented changes in
behavior or performance changes (positive or negative).

Most changes in the first release are listed below. For more details, please
see the commit log, which reflects a linear and decently documented history
of all changes.

New features:

• FEATURE #​501:
  Permit many more characters to be escaped, even if they have no significance.
  More specifically, any ASCII character except for [0-9A-Za-z<>] can now be
  escaped. Also, a new routine, is_escapeable_character, has been added to
  regex-syntax to query whether a character is escapeable or not.
• FEATURE #​547:
  Add Regex::captures_at. This fills a hole in the API, but doesn't otherwise
  introduce any new expressive power.
• FEATURE #​595:
  Capture group names are now Unicode-aware. They can now begin with either a _
  or any "alphabetic" codepoint. After the first codepoint, subsequent codepoints
  can be any sequence of alpha-numeric codepoints, along with _, ., [ and
  ]. Note that replacement syntax has not changed.
• FEATURE #​810:
  Add Match::is_empty and Match::len APIs.
• FEATURE #​905:
  Add an impl Default for RegexSet, with the default being the empty set.
• FEATURE #​908:
  A new method, Regex::static_captures_len, has been added which returns the
  number of capture groups in the pattern if and only if every possible match
  always contains the same number of matching groups.
• FEATURE #​955:
  Named captures can now be written as (?<name>re) in addition to
  (?P<name>re).
• FEATURE: regex-syntax now supports empty character classes.
• FEATURE: regex-syntax now has an optional std feature. (This will come
  to regex in the second release.)
• FEATURE: The Hir type in regex-syntax has had a number of simplifications
  made to it.
• FEATURE: regex-syntax has support for a new R flag for enabling CRLF
  mode. This will be supported in regex proper in the second release.
• FEATURE: regex-syntax now has proper support for "regex that never
  matches" via Hir::fail().
• FEATURE: The hir::literal module of regex-syntax has been completely
  re-worked. It now has more documentation, examples and advice.
• FEATURE: The allow_invalid_utf8 option in regex-syntax has been renamed
  to utf8, and the meaning of the boolean has been flipped.

Performance improvements:

• PERF: The upgrade to aho-corasick 1.0 may improve performance in some
  cases. It's difficult to characterize exactly which patterns this might impact,
  but if there are a small number of longish (>= 4 bytes) prefix literals, then
  it might be faster than before.

Bug fixes:

• BUG #​514:
  Improve Debug impl for Match so that it doesn't show the entire haystack.
• BUGS #​516,
  #​731:
  Fix a number of issues with printing Hir values as regex patterns.
• BUG #​610:
  Add explicit example of foo|bar in the regex syntax docs.
• BUG #​625:
  Clarify that SetMatches::len does not (regretably) refer to the number of
  matches in the set.
• BUG #​660:
  Clarify "verbose mode" in regex syntax documentation.
• BUG #​738,
  #​950:
  Fix CaptureLocations::get so that it never panics.
• BUG #​747:
  Clarify documentation for Regex::shortest_match.
• BUG #​835:
  Fix \p{Sc} so that it is equivalent to \p{Currency_Symbol}.
• BUG #​846:
  Add more clarifying documentation to the CompiledTooBig error variant.
• BUG #​854:
  Clarify that regex::Regex searches as if the haystack is a sequence of
  Unicode scalar values.
• BUG #​884:
  Replace __Nonexhaustive variants with #[non_exhaustive] attribute.
• BUG #​893:
  Optimize case folding since it can get quite slow in some pathological cases.
• BUG #​895:
  Reject (?-u:\W) in regex::Regex APIs.
• BUG #​942:
  Add a missing void keyword to indicate "no parameters" in C API.
• BUG #​965:
  Fix \p{Lc} so that it is equivalent to \p{Cased_Letter}.
• BUG #​975:
  Clarify documentation for \pX syntax.

v1.7.3

Compare Source

==================
This is a small release that fixes a bug in Regex::shortest_match_at that
could cause it to panic, even when the offset given is valid.

Bug fixes:

• BUG #​969:
  Fix a bug in how the reverse DFA was called for Regex::shortest_match_at.

v1.7.2

Compare Source

==================
This is a small release that fixes a failing test on FreeBSD.

Bug fixes:

• BUG #​967:
  Fix "no stack overflow" test which can fail due to the small stack size.

v1.7.1

Compare Source

==================
This release was done principally to try and fix the doc.rs rendering for the
regex crate.

Performance improvements:

• PERF #​930:
  Optimize replacen. This also applies to replace, but not replace_all.

Bug fixes:

• BUG #​945:
  Maybe fix rustdoc rendering by just bumping a new release?

v1.7.0

Compare Source

==================
This release principally includes an upgrade to Unicode 15.

New features:

• FEATURE #​832:
  Upgrade to Unicode 15.

v0.16.0

Compare Source

This release marks Options as non_exhaustive and extends it to
make line endings configurable, it adds new fast paths to fill and
wrap, and it fixes crashes in unfill and refill.

• #​480: Mark
  Options as non_exhaustive. This will allow us to extend the
  struct in the future without breaking backwards compatibility.
• #​478: Add fast
  paths to fill and wrap. This makes the functions 10-25 times
  faster when the no wrapping is needed.
• #​468: Fix refill
  to add back correct line ending.
• #​467: Fix crashes
  in unfill and refill.
• #​458: Test with
  Rust 1.56 (first compiler release with support for Rust 2021).
• #​454: Make line
  endings configurable.
• #​448: Migrate to
  the Rust 2021 edition.

v0.15.2

Compare Source

This release is identical to 0.15.0 and is only there to give people a
way to install crates which depend on the yanked 0.15.1 release. See
#​484 for details.

v0.15.1

Compare Source

This release was yanked since it accidentally broke backwards
compatibility with 0.15.0.

v0.15.0

Compare Source

This is a major feature release with two main changes:

• #​421: Use f64
  instead of usize for fragment widths.

  This fixes problems with overflows in the internal computations of
  wrap_optimal_fit when fragments (words) or line lengths had
  extreme values, such as usize::MAX.

• #​438: Simplify
  Options by removing generic type parameters.

  This change removes the new generic parameters introduced in version
  0.14, as well as the original WrapSplitter parameter which has
  been present since very early versions.

  The result is a simplification of function and struct signatures
  across the board. So what used to be

  let options: Options<
      wrap_algorithms::FirstFit,
      word_separators::AsciiSpace,
      word_splitters::HyphenSplitter,
  > = Options::new(80);

  if types are fully written out, is now simply

  let options: Options<'_> = Options::new(80);

  The anonymous lifetime represent the lifetime of the
  initial_indent and subsequent_indent strings. The change is
  nearly performance neutral (a 1-2% regression).

Smaller improvements and changes:

• #​404: Make
  documentation for short last-line penalty more precise.
• #​405: Cleanup and
  simplify Options docstring.
• #​411: Default to
  OptimalFit in interactive example.
• #​415: Add demo
  program to help compute binary sizes.
• #​423: Add fuzz
  tests with fully arbitrary fragments.
• #​424: Change
  wrap_optimal_fit penalties to non-negative numbers.
• #​430: Add
  debug-words example.
• #​432: Use precise
  dependency versions in Cargo.toml.

v0.14.2

Compare Source

The 0.14.1 release included more changes than intended and has been
yanked. The change intended for 0.14.1 is now included in 0.14.2.

v0.14.1

Compare Source

This release fixes a panic reported by @​Makoto, thanks!

• #​391: Fix panic in
  find_words due to string access outside of a character boundary.

v0.14.0

Compare Source

This is a major feature release which makes Textwrap more configurable
and flexible. The high-level API of textwrap::wrap and
textwrap::fill remains unchanged, but low-level structs have moved
around.

The biggest change is the introduction of new generic type parameters
to the Options struct. These parameters lets you statically
configure the wrapping algorithm, the word separator, and the word
splitter. If you previously spelled out the full type for Options,
you now need to take the extra type parameters into account. This
means that

let options: Options<HyphenSplitter> = Options::new(80);

changes to

let options: Options<
    wrap_algorithms::FirstFit,
    word_separators::AsciiSpace,
    word_splitters::HyphenSplitter,
> = Options::new(80);

This is quite a mouthful, so we suggest using type inference where
possible. You won’t see any chance if you call wrap directly with a
width or with an Options value constructed on the fly. Please open
an issue if this causes problems for you!

New WordSeparator Trait

• #​332: Add
  WordSeparator trait to allow customizing how words are found in a
  line of text. Until now, Textwrap would always assume that words are
  separated by ASCII space characters. You can now customize this as
  needed.

• #​313: Add support
  for using the Unicode line breaking algorithm to find words. This is
  done by adding a second implementation of the new WordSeparator
  trait. The implementation uses the unicode-linebreak crate, which is
  a new optional dependency.

  With this, Textwrap can be used with East-Asian languages such as
  Chinese or Japanese where there are no spaces between words.
  Breaking a long sequence of emojis is another example where line
  breaks might be wanted even if there are no whitespace to be found.
  Feedback would be appreciated for this feature.

Indent

• #​353: Trim trailing
  whitespace from prefix in indent.

  Before, empty lines would get no prefix added. Now, empty lines have
  a trimmed prefix added. This little trick makes indent much more
  useful since you can now safely indent with "# " without creating
  trailing whitespace in the output due to the trailing whitespace in
  your prefix.

• #​354: Make indent
  about 20% faster by preallocating the output string.

Documentation

• #​308: Document
  handling of leading and trailing whitespace when wrapping text.

WebAssembly Demo

• #​310: Thanks to
  WebAssembly, you can now try out Textwrap directly in your browser.
  Please try it out: https://mgeisler.github.io/textwrap/.

New Generic Parameters

• #​331: Remove outer
  boxing from Options.

• #​357: Replace
  core::WrapAlgorithm enum with a wrap_algorithms::WrapAlgorithm
  trait. This allows for arbitrary wrapping algorithms to be plugged
  into the library.

• #​358: Switch
  wrapping functions to use a slice for line_widths.

• #​368: Move
  WordSeparator and WordSplitter traits to separate modules.
  Before, Textwrap had several top-level structs such as
  NoHyphenation and HyphenSplitter. These implementations of
  WordSplitter now lives in a dedicated word_splitters module.
  Similarly, we have a new word_separators module for
  implementations of WordSeparator.

• #​369: Rename
  Options::splitter to Options::word_splitter for consistency with
  the other fields backed by traits.

v0.13.4

Compare Source

This release removes println! statements which was left behind in
unfill by mistake.

• #​296: Improve house
  building example with more comments.
• #​297: Remove debug
  prints in the new unfill function.

v0.13.3

Compare Source

This release contains a bugfix for indent and improved handling of
emojis. We’ve also added a new function for formatting text in columns
and functions for reformatting already wrapped text.

• #​276: Extend
  core::display_width to handle emojis when the unicode-width Cargo
  feature is disabled.
• #​279: Make indent
  preserve existing newlines in the input string. Before,
  indent("foo", "") would return "foo\n" by mistake. It now
  returns "foo" instead.
• #​281: Ensure all
  Options fields have examples.
• #​282: Add a
  wrap_columns function.
• #​294: Add new
  unfill and refill functions.

v0.13.2

Compare Source

This release primarily makes all dependencies optional. This makes it
possible to slim down textwrap as needed.

• #​254: impl WordSplitter for Box<T> where T: WordSplitter.
• #​255: Use command
  line arguments as initial text in interactive example.
• #​256: Introduce
  fuzz tests for wrap_optimal_fit and wrap_first_fit.
• #​260: Make the
  unicode-width dependency optional.
• #​261: Make the
  smawk dependency optional.

v0.13.1

Compare Source

This is a bugfix release which fixes a regression in 0.13.0. The bug
meant that colored text was wrapped incorrectly.

• #​245: Support
  deleting a word with Ctrl-Backspace in the interactive demo.
• #​246: Show build
  type (debug/release) in interactive demo.
• #​249: Correctly
  compute width while skipping over ANSI escape sequences.

v0.13.0

Compare Source

This is a major release which rewrites the core logic, adds many new
features, and fixes a couple of bugs. Most programs which use
textwrap stays the same, incompatibilities and upgrade notes are
given below.

Clone the repository and run the following to explore the new features
in an interactive demo (Linux only):

$ cargo run --example interactive --all-features

Bug Fixes

Rewritten core wrapping algorithm

• #​221: Reformulate
  wrapping in terms of words with whitespace and penalties.

The core wrapping algorithm has been completely rewritten. This fixed
bugs and simplified the code, while also making it possible to use
textwrap outside the context of the terminal.

As part of this, trailing whitespace is now discarded consistently
from wrapped lines. Before we would inconsistently remove whitespace
at the end of wrapped lines, except for the last. Leading whitespace
is still preserved.

New Features

Optimal-fit wrapping

• #​234: Introduce
  wrapping using an optimal-fit algorithm.

This release adds support for new wrapping algorithm which finds a
globally optimal set of line breaks, taking certain penalties into
account. As an example, the old algorithm would produce

"To be, or"
"not to be:"
"that is"
"the"
"question"

Notice how the fourth line with “the” is very short. The new algorithm
shortens the previous lines slightly to produce fewer short lines:

"To be,"
"or not to"
"be: that"
"is the"
"question"

Use the new textwrap::core::WrapAlgorithm enum to select between the
new and old algorithm. By default, the new algorithm is used.

The optimal-fit algorithm is inspired by the line breaking algorithm
used in TeX, described in the 1981 article Breaking Paragraphs into
Lines by
Knuth and Plass.

In-place wrapping

• #​226: Add a
  fill_inplace function.

When the text you want to fill is already a temporary String, you
can now mutate it in-place with fill_inplace:

let mut greeting = format!("Greetings {}, welcome to the game! You have {} lives left.",
                           player.name, player.lives);
fill_inplace(&mut greeting, line_width);

This is faster than calling fill and it will reuse the memory
already allocated for the string.

Changed Features

Wrapper is replaced with Options

• #​213: Simplify API
  with only top-level functions.
• #​215: Reintroducing
  the type parameter on Options (previously known as Wrapper).
• #​219: Allow using
  trait objects with fill & wrap.
• #​227: Replace
  WrapOptions with Into<Options>.

The Wrapper struct held the options (line width, indentation, etc)
for wrapping text. It was also the entry point for actually wrapping
the text via its methods such as wrap, wrap_iter,
into_wrap_iter, and fill methods.

The struct has been replaced by a simpler Options struct which only
holds options. The Wrapper methods are gone, their job has been
taken over by the top-level wrap and fill functions. The signature
of these functions have changed from

fn fill(s: &str, width: usize) -> String;

fn wrap(s: &str, width: usize) -> Vec<Cow<'_, str>>;

to the more general

fn fill<'a, S, Opt>(text: &str, options: Opt) -> String
where
    S: WordSplitter,
    Opt: Into<Options<'a, S>>;

fn wrap<'a, S, Opt>(text: &str, options: Opt) -> Vec<Cow<'_, str>>
where
    S: WordSplitter,
    Opt: Into<Options<'a, S>>;

The Into<Options<'a, S> bound allows you to pass an usize (which
is interpreted as the line width) and a full Options object. This
allows the new functions to work like the old, plus you can now fully
customize the behavior of the wrapping via Options when needed.

Code that call textwrap::wrap or textwrap::fill can remain
unchanged. Code that calls into Wrapper::wrap or Wrapper::fill
will need to be update. This is a mechanical change, please see
#​213 for examples.

Thanks to @​CryptJar and @​Koxiat for their support in the PRs above!

Removed Features

• The wrap_iter and into_wrap_iter methods are gone. This means
  that lazy iteration is no longer supported: you always get all
  wrapped lines back as a Vec. This was done to simplify the code
  and to support the optimal-fit algorithm.

  The first-fit algorithm could still be implemented in an incremental
  fashion. Please let us know if this is important to you.

Other Changes

• #​206: Change
  Wrapper.splitter from T: WordSplitter to Box<dyn WordSplitter>.
• #​216: Forbid the
  use of unsafe code.

v0.12.1

Compare Source

This is a bugfix release.

• Fixed [#​176][issue-176]: Mention compile-time wrapping by linking to
  the [textwrap-macros crate].
• Fixed [#​193][issue-193]: Wrapping with break_words(false) was
  broken and would cause extra whitespace to be inserted when words
  were longer than the line width.

v0.12.0

Compare Source

The code has been updated to the [Rust 2018 edition][rust-2018] and
each new release of textwrap will only support the latest stable
version of Rust. Trying to support older Rust versions is a fool's
errand: our dependencies keep releasing new patch versions that
require newer and newer versions of Rust.

The term_size feature has been replaced by terminal_size. The API
is unchanged, it is just the name of the Cargo feature that changed.

The hyphenation feature now only embeds the hyphenation patterns for
US-English. This slims down the dependency.

• Fixed [#​140][issue-140]: Ignore ANSI escape sequences.
• Fixed [#​158][issue-158]: Unintended wrapping when using external splitter.
• Fixed [#​177][issue-177]: Update examples to the 2018 edition.