evan/ludum-dare-50
Archived
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2022-04-04. You can view files and clone it, but cannot push or open issues or pull requests.
ludum-dare-50/rustdoc/textwrap/index.html

172 lines
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="The textwrap library provides functions for word wrapping and indenting text."><meta name="keywords" content="rust, rustlang, rust-lang, textwrap"><title>textwrap - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" type="text/css" href="../normalize.css"><link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../ayu.css" disabled><link rel="stylesheet" type="text/css" href="../dark.css" disabled><link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script src="../crates.js"></script><script defer src="../main.js"></script>
<noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../favicon.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu" role="button">&#9776;</div><a class="sidebar-logo" href="../textwrap/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.png" alt="logo"></div>
</a><h2 class="location">Crate textwrap</h2><div class="block version"><div class="narrow-helper"></div><p>Version 0.15.0</p></div><div class="sidebar-elems"><a id="all-types" href="all.html"><p>See all textwrap's items</p></a><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#functions">Functions</a></li></ul></div><div id="sidebar-vars" data-name="textwrap" data-ty="mod" data-relpath=""></div><script defer src="sidebar-items.js"></script></div></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../textwrap/index.html"><img class="rust-logo" src="../rust-logo.png" alt="logo"></a><nav class="sub"><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu" title="themes"><img width="18" height="18" alt="Pick another theme!" src="../brush.svg"></button><div id="theme-choices" role="menu"></div></div><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><button type="button" id="help-button" title="help">?</button><a id="settings-menu" href="../settings.html" title="settings"><img width="18" height="18" alt="Change settings" src="../wheel.svg"></a></div></form></nav></div><section id="main-content" class="content"><h1 class="fqn"><span class="in-band">Crate <a class="mod" href="#">textwrap</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></span><span class="out-of-band"><span id="render-detail"><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">&#x2212;</span>]</a></span><a class="srclink" href="../src/textwrap/lib.rs.html#1-1847" title="goto source code">[src]</a></span></h1><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>The textwrap library provides functions for word wrapping and
indenting text.</p>
<h2 id="wrapping-text" class="section-header"><a href="#wrapping-text">Wrapping Text</a></h2>
<p>Wrapping text can be very useful in command-line programs where
you want to format dynamic output nicely so it looks good in a
terminal. A quick example:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let</span> <span class="ident">text</span> <span class="op">=</span> <span class="string">&quot;textwrap: a small library for wrapping text.&quot;</span>;
<span class="macro">assert_eq!</span>(<span class="ident">textwrap::wrap</span>(<span class="ident">text</span>, <span class="number">18</span>),
<span class="macro">vec!</span>[<span class="string">&quot;textwrap: a&quot;</span>,
<span class="string">&quot;small library for&quot;</span>,
<span class="string">&quot;wrapping text.&quot;</span>]);</code></pre></div>
<p>The <a href="fn.wrap.html" title="wrap"><code>wrap</code></a> function returns the individual lines, use <a href="fn.fill.html" title="fill"><code>fill</code></a>
is you want the lines joined with <code>'\n'</code> to form a <code>String</code>.</p>
<p>If you enable the <code>hyphenation</code> Cargo feature, you can get
automatic hyphenation for a number of languages:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">feature</span> <span class="op">=</span> <span class="string">&quot;hyphenation&quot;</span>)]</span> {
<span class="kw">use</span> <span class="ident">hyphenation</span>::{<span class="ident">Language</span>, <span class="ident">Load</span>, <span class="ident">Standard</span>};
<span class="kw">use</span> <span class="ident">textwrap</span>::{<span class="ident">wrap</span>, <span class="ident">Options</span>, <span class="ident">WordSplitter</span>};
<span class="kw">let</span> <span class="ident">text</span> <span class="op">=</span> <span class="string">&quot;textwrap: a small library for wrapping text.&quot;</span>;
<span class="kw">let</span> <span class="ident">dictionary</span> <span class="op">=</span> <span class="ident">Standard::from_embedded</span>(<span class="ident">Language::EnglishUS</span>).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="ident">options</span> <span class="op">=</span> <span class="ident">Options::new</span>(<span class="number">18</span>).<span class="ident">word_splitter</span>(<span class="ident">WordSplitter::Hyphenation</span>(<span class="ident">dictionary</span>));
<span class="macro">assert_eq!</span>(<span class="ident">wrap</span>(<span class="ident">text</span>, <span class="kw-2">&amp;</span><span class="ident">options</span>),
<span class="macro">vec!</span>[<span class="string">&quot;textwrap: a small&quot;</span>,
<span class="string">&quot;library for wrap-&quot;</span>,
<span class="string">&quot;ping text.&quot;</span>]);
}</code></pre></div>
<p>See also the <a href="fn.unfill.html" title="unfill"><code>unfill</code></a> and <a href="fn.refill.html" title="refill"><code>refill</code></a> functions which allow you to
manipulate already wrapped text.</p>
<h3 id="wrapping-strings-at-compile-time" class="section-header"><a href="#wrapping-strings-at-compile-time">Wrapping Strings at Compile Time</a></h3>
<p>If your strings are known at compile time, please take a look at
the procedural macros from the <a href="https://docs.rs/textwrap-macros/">textwrap-macros</a> crate.</p>
<h3 id="displayed-width-vs-byte-size" class="section-header"><a href="#displayed-width-vs-byte-size">Displayed Width vs Byte Size</a></h3>
<p>To word wrap text, one must know the width of each word so one can
know when to break lines. This library will by default measure the
width of text using the <em>displayed width</em>, not the size in bytes.
The <code>unicode-width</code> Cargo feature controls this.</p>
<p>This is important for non-ASCII text. ASCII characters such as <code>a</code>
and <code>!</code> are simple and take up one column each. This means that
the displayed width is equal to the string length in bytes.
However, non-ASCII characters and symbols take up more than one
byte when UTF-8 encoded: <code>é</code> is <code>0xc3 0xa9</code> (two bytes) and <code>⚙</code> is
<code>0xe2 0x9a 0x99</code> (three bytes) in UTF-8, respectively.</p>
<p>This is why we take care to use the displayed width instead of the
byte count when computing line lengths. All functions in this
library handle Unicode characters like this when the
<code>unicode-width</code> Cargo feature is enabled (it is enabled by
default).</p>
<h2 id="indentation-and-dedentation" class="section-header"><a href="#indentation-and-dedentation">Indentation and Dedentation</a></h2>
<p>The textwrap library also offers functions for adding a prefix to
every line of a string and to remove leading whitespace. As an
example, the <a href="fn.indent.html" title="indent"><code>indent</code></a> function allows you to turn lines of text
into a bullet list:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let</span> <span class="ident">before</span> <span class="op">=</span> <span class="string">&quot;\
foo
bar
baz
&quot;</span>;
<span class="kw">let</span> <span class="ident">after</span> <span class="op">=</span> <span class="string">&quot;\
* foo
* bar
* baz
&quot;</span>;
<span class="macro">assert_eq!</span>(<span class="ident">textwrap::indent</span>(<span class="ident">before</span>, <span class="string">&quot;* &quot;</span>), <span class="ident">after</span>);</code></pre></div>
<p>Removing leading whitespace is done with <a href="fn.dedent.html" title="dedent"><code>dedent</code></a>:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let</span> <span class="ident">before</span> <span class="op">=</span> <span class="string">&quot;
Some
indented
text
&quot;</span>;
<span class="kw">let</span> <span class="ident">after</span> <span class="op">=</span> <span class="string">&quot;
Some
indented
text
&quot;</span>;
<span class="macro">assert_eq!</span>(<span class="ident">textwrap::dedent</span>(<span class="ident">before</span>), <span class="ident">after</span>);</code></pre></div>
<h2 id="cargo-features" class="section-header"><a href="#cargo-features">Cargo Features</a></h2>
<p>The textwrap library can be slimmed down as needed via a number of
Cargo features. This means you only pay for the features you
actually use.</p>
<p>The full dependency graph, where dashed lines indicate optional
dependencies, is shown below:</p>
<img src="https://raw.githubusercontent.com/mgeisler/textwrap/master/images/textwrap-0.15.0.svg">
<h3 id="default-features" class="section-header"><a href="#default-features">Default Features</a></h3>
<p>These features are enabled by default:</p>
<ul>
<li>
<p><code>unicode-linebreak</code>: enables finding words using the
<a href="https://docs.rs/unicode-linebreak/">unicode-linebreak</a> crate, which implements the line breaking
algorithm described in <a href="https://www.unicode.org/reports/tr14/">Unicode Standard Annex
#14</a>.</p>
<p>This feature can be disabled if you are happy to find words
separated by ASCII space characters only. People wrapping text
with emojis or East-Asian characters will want most likely want
to enable this feature. See <a href="enum.WordSeparator.html" title="WordSeparator"><code>WordSeparator</code></a> for details.</p>
</li>
<li>
<p><code>unicode-width</code>: enables correct width computation of non-ASCII
characters via the <a href="https://docs.rs/unicode-width/">unicode-width</a> crate. Without this feature,
every <a href="https://doc.rust-lang.org/1.59.0/std/primitive.char.html" title="char"><code>char</code></a> is 1 column wide, except for emojis which are 2
columns wide. See the <a href="core/fn.display_width.html" title="core::display_width"><code>core::display_width</code></a> function for
details.</p>
<p>This feature can be disabled if you only need to wrap ASCII
text, or if the functions in <a href="core/index.html" title="core"><code>core</code></a> are used directly with
<a href="core/trait.Fragment.html" title="core::Fragment"><code>core::Fragment</code></a>s for which the widths have been computed in
other ways.</p>
</li>
<li>
<p><code>smawk</code>: enables linear-time wrapping of the whole paragraph via
the <a href="https://docs.rs/smawk/">smawk</a> crate. See the [<code>wrap_algorithms::wrap_optimal_fit</code>]
function for details on the optimal-fit algorithm.</p>
<p>This feature can be disabled if you only ever intend to use
<a href="wrap_algorithms/fn.wrap_first_fit.html" title="wrap_algorithms::wrap_first_fit"><code>wrap_algorithms::wrap_first_fit</code></a>.</p>
</li>
</ul>
<p>With Rust 1.59.0, the size impact of the above features on your
binary is as follows:</p>
<div><table><thead><tr><th style="text-align: left">Configuration</th><th style="text-align: right">Binary Size</th><th style="text-align: right">Delta</th></tr></thead><tbody>
<tr><td style="text-align: left">quick-and-dirty implementation</td><td style="text-align: right">289 KB</td><td style="text-align: right">— KB</td></tr>
<tr><td style="text-align: left">textwrap without default features</td><td style="text-align: right">301 KB</td><td style="text-align: right">12 KB</td></tr>
<tr><td style="text-align: left">textwrap with smawk</td><td style="text-align: right">317 KB</td><td style="text-align: right">28 KB</td></tr>
<tr><td style="text-align: left">textwrap with unicode-width</td><td style="text-align: right">313 KB</td><td style="text-align: right">24 KB</td></tr>
<tr><td style="text-align: left">textwrap with unicode-linebreak</td><td style="text-align: right">395 KB</td><td style="text-align: right">106 KB</td></tr>
</tbody></table>
</div>
<p>The above sizes are the stripped sizes and the binary is compiled
in release mode with this profile:</p>
<div class="example-wrap"><pre class="language-toml"><code>[profile.release]
lto = true
codegen-units = 1</code></pre></div>
<p>See the <a href="https://github.com/mgeisler/textwrap/tree/master/examples/binary-sizes">binary-sizes demo</a> if you want to reproduce these
results.</p>
<h3 id="optional-features" class="section-header"><a href="#optional-features">Optional Features</a></h3>
<p>These Cargo features enable new functionality:</p>
<ul>
<li>
<p><code>terminal_size</code>: enables automatic detection of the terminal
width via the <a href="https://docs.rs/terminal_size/">terminal_size</a> crate. See the
[<code>Options::with_termwidth</code>] constructor for details.</p>
</li>
<li>
<p><code>hyphenation</code>: enables language-sensitive hyphenation via the
<a href="https://docs.rs/hyphenation/">hyphenation</a> crate. See the <a href="word_splitters/enum.WordSplitter.html" title="word_splitters::WordSplitter"><code>word_splitters::WordSplitter</code></a>
trait for details.</p>
</li>
</ul>
</div></details><h2 id="reexports" class="small-section-header"><a href="#reexports">Re-exports</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left import-item"><code>pub use word_splitters::<a class="enum" href="word_splitters/enum.WordSplitter.html" title="enum textwrap::word_splitters::WordSplitter">WordSplitter</a>;</code></div><div class="item-right docblock-short"></div></div><div class="item-row"><div class="item-left import-item"><code>pub use wrap_algorithms::<a class="enum" href="wrap_algorithms/enum.WrapAlgorithm.html" title="enum textwrap::wrap_algorithms::WrapAlgorithm">WrapAlgorithm</a>;</code></div><div class="item-right docblock-short"></div></div></div><h2 id="modules" class="small-section-header"><a href="#modules">Modules</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="mod" href="core/index.html" title="textwrap::core mod">core</a></div><div class="item-right docblock-short"><p>Building blocks for advanced wrapping functionality.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="word_splitters/index.html" title="textwrap::word_splitters mod">word_splitters</a></div><div class="item-right docblock-short"><p>Word splitting functionality.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="wrap_algorithms/index.html" title="textwrap::wrap_algorithms mod">wrap_algorithms</a></div><div class="item-right docblock-short"><p>Word wrapping algorithms.</p>
</div></div></div><h2 id="structs" class="small-section-header"><a href="#structs">Structs</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.Options.html" title="textwrap::Options struct">Options</a></div><div class="item-right docblock-short"><p>Holds configuration options for wrapping and filling text.</p>
</div></div></div><h2 id="enums" class="small-section-header"><a href="#enums">Enums</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.WordSeparator.html" title="textwrap::WordSeparator enum">WordSeparator</a></div><div class="item-right docblock-short"><p>Describes where words occur in a line of text.</p>
</div></div></div><h2 id="functions" class="small-section-header"><a href="#functions">Functions</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.dedent.html" title="textwrap::dedent fn">dedent</a></div><div class="item-right docblock-short"><p>Removes common leading whitespace from each line.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.fill.html" title="textwrap::fill fn">fill</a></div><div class="item-right docblock-short"><p>Fill a line of text at a given width.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.fill_inplace.html" title="textwrap::fill_inplace fn">fill_inplace</a></div><div class="item-right docblock-short"><p>Fill <code>text</code> in-place without reallocating the input string.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.indent.html" title="textwrap::indent fn">indent</a></div><div class="item-right docblock-short"><p>Indent each line by the given prefix.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.refill.html" title="textwrap::refill fn">refill</a></div><div class="item-right docblock-short"><p>Refill a paragraph of wrapped text with a new width.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.unfill.html" title="textwrap::unfill fn">unfill</a></div><div class="item-right docblock-short"><p>Unpack a paragraph of already-wrapped text.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.wrap.html" title="textwrap::wrap fn">wrap</a></div><div class="item-right docblock-short"><p>Wrap a line of text at a given width.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.wrap_columns.html" title="textwrap::wrap_columns fn">wrap_columns</a></div><div class="item-right docblock-short"><p>Wrap text into columns with a given total width.</p>
</div></div></div></section><section id="search" class="content hidden"></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="textwrap" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.59.0 (9d1b2106e 2022-02-23)" ></div>
</body></html>
Reference in New Issue View Git Blame Copy Permalink