<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="This is a library for controlling colors and formatting, such as red bold text or blue underlined text, on ANSI terminals."><title>nu_ansi_term - Rust</title><script>if(window.location.protocol!=="file:")document.write(`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2">`)</script><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-e935ef01ae1c1829.css"><metaname="rustdoc-vars"data-root-path="../"data-static-root-path="../static.files/"data-current-crate="nu_ansi_term"data-themes=""data-resource-suffix=""data-rustdoc-version="1.78.0 (9b00956e5 2024-04-29)"data-channel="1.78.0"data-search-js="search-42d8da7a6b9792c2.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../static.files/storage-4c98445ec4002617.js"></script><scriptdefersrc="../crates.js"></script><scriptdefersrc="../static.files/main-12cf3b4f4f9dc36d.js"></script><noscript><linkrel="stylesheet"href="../static.files/noscript-04d5337699b92874.css"></noscript><linkrel="alternate icon"type="image/png"href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button></nav><navclass="sidebar"><divclass="sidebar-crate"><h2><ahref="../nu_ansi_term/index.html">nu_ansi_term</a><spanclass="version">0.46.0</span></h2></div><divclass="sidebar-elems"><ulclass="block">
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../nu_ansi_term/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Crate <aclass="mod"href="#">nu_ansi_term</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../src/nu_ansi_term/lib.rs.html#1-272">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>This is a library for controlling colors and formatting, such as
red bold text or blue underlined text, on ANSI terminals.</p>
<p>There are three main types in this crate that you need to be
concerned with: <ahref="type.AnsiString.html"><code>AnsiString</code></a>, <ahref="struct.Style.html"><code>Style</code></a>, and <ahref="enum.Color.html"><code>Color</code></a>.</p>
<p>A <code>Style</code> holds stylistic information: foreground and background colors,
whether the text should be bold, or blinking, or other properties. The
<ahref="enum.Color.html"><code>Color</code></a> enum represents the available colors. And an <ahref="type.AnsiString.html"><code>AnsiString</code></a> is a
string paired with a <ahref="struct.Style.html"><code>Style</code></a>.</p>
<p><ahref="enum.Color.html"><code>Color</code></a> is also available as an alias to <code>Color</code>.</p>
<p>To format a string, call the <code>paint</code> method on a <code>Style</code> or a <code>Color</code>,
passing in the string you want to format as the argument. For example,
<spanclass="macro">println!</span>(<spanclass="string">"This is in red: {}"</span>, Red.paint(<spanclass="string">"a red string"</span>));</code></pre></div>
<p>It’s important to note that the <code>paint</code> method does <em>not</em> actually return a
string with the ANSI control characters surrounding it. Instead, it returns
an <ahref="type.AnsiString.html"><code>AnsiString</code></a> value that has a <ahref="https://doc.rust-lang.org/std/fmt/trait.Display.html"><code>Display</code></a> implementation that, when
formatted, returns the characters. This allows strings to be printed with a
minimum of <ahref="https://doc.rust-lang.org/std/string/struct.String.html"><code>String</code></a> allocations being performed behind the scenes.</p>
<p>If you <em>do</em> want to get at the escape codes, then you can convert the
<ahref="type.AnsiString.html"><code>AnsiString</code></a> to a string as you would any other <code>Display</code> value:</p>
<h3id="bold-underline-background-and-other-styles"><aclass="doc-anchor"href="#bold-underline-background-and-other-styles">§</a>Bold, underline, background, and other styles</h3>
<spanclass="macro">println!</span>(<spanclass="string">"Yellow on blue: {}"</span>, Yellow.on(Blue).paint(<spanclass="string">"wow!"</span>));</code></pre></div>
<p>The complete list of styles you can use are: <ahref="struct.Style.html#method.bold"><code>bold</code></a>, <ahref="struct.Style.html#method.dimmed"><code>dimmed</code></a>, <ahref="struct.Style.html#method.italic"><code>italic</code></a>,
<ahref="struct.Style.html#method.underline"><code>underline</code></a>, <ahref="struct.Style.html#method.blink"><code>blink</code></a>, <ahref="struct.Style.html#method.reverse"><code>reverse</code></a>, <ahref="struct.Style.html#method.hidden"><code>hidden</code></a>, <ahref="struct.Style.html#method.strikethrough"><code>strikethrough</code></a>, and <ahref="struct.Style.html#method.on"><code>on</code></a> for
background colors.</p>
<p>In some cases, you may find it easier to change the foreground on an
existing <code>Style</code> rather than starting from the appropriate <code>Color</code>.
You can do this using the <ahref="struct.Style.html#method.fg"><code>fg</code></a> method:</p>
<spanclass="macro">println!</span>(<spanclass="string">"Yellow on blue: {}"</span>, Style::new().on(Blue).fg(Yellow).paint(<spanclass="string">"yow!"</span>));
<spanclass="macro">println!</span>(<spanclass="string">"Also yellow on blue: {}"</span>, Cyan.on(Blue).fg(Yellow).paint(<spanclass="string">"zow!"</span>));</code></pre></div>
<p>You can turn a <code>Color</code> into a <code>Style</code> with the <ahref="enum.Color.html#method.normal"><code>normal</code></a> method.
This will produce the exact same <code>AnsiString</code> as if you just used the
<code>paint</code> method on the <code>Color</code> directly, but it’s useful in certain cases:
for example, you may have a method that returns <code>Styles</code>, and need to
represent both the “red bold” and “red, but not bold” styles with values of
the same type. The <code>Style</code> struct also has a <ahref="https://doc.rust-lang.org/std/default/trait.Default.html"><code>Default</code></a> implementation if you
want to have a style with <em>nothing</em> set.</p>
Fixed(<spanclass="number">134</span>).paint(<spanclass="string">"A sort of light purple"</span>);
Fixed(<spanclass="number">221</span>).on(Fixed(<spanclass="number">124</span>)).paint(<spanclass="string">"Mustard in the ketchup"</span>);</code></pre></div>
<p>The first sixteen of these values are the same as the normal and bold
standard color variants. There’s nothing stopping you from using these as
<code>Fixed</code> colors instead, but there’s nothing to be gained by doing so
either.</p>
<p>You can also access full 24-bit color by using the <code>Color::Rgb</code> variant,
which takes separate <code>u8</code> arguments for red, green, and blue:</p>
<p>There are several things to note here. Firstly, the <ahref="type.AnsiByteString.html#method.write_to"><code>paint</code></a> method can take
<em>either</em> an owned <ahref="https://doc.rust-lang.org/std/string/struct.String.html"><code>String</code></a> or a borrowed <ahref="https://doc.rust-lang.org/std/primitive.str.html"><code>&str</code></a>. Internally, an <ahref="type.AnsiString.html"><code>AnsiString</code></a>
holds a copy-on-write (<ahref="https://doc.rust-lang.org/std/borrow/enum.Cow.html"><code>Cow</code></a>) string value to deal with both owned and
borrowed strings at the same time. This is used here to display a <code>String</code>,
the result of the <code>format!</code> call, using the same mechanism as some
statically-available <code>&str</code> slices. Secondly, that the <ahref="type.AnsiStrings.html"><code>AnsiStrings</code></a> value
works in the same way as its singular counterpart, with a <ahref="https://doc.rust-lang.org/std/fmt/trait.Display.html"><code>Display</code></a>
implementation that only performs the formatting when required.</p>
<p>This library also supports formatting <code>\[u8]</code> byte strings; this supports
applications working with text in an unknown encoding. <ahref="struct.Style.html"><code>Style</code></a> and
<ahref="enum.Color.html"><code>Color</code></a> support painting <code>\[u8]</code> values, resulting in an <ahref="type.AnsiByteString.html"><code>AnsiByteString</code></a>.
This type does not implement <ahref="https://doc.rust-lang.org/std/fmt/trait.Display.html"><code>Display</code></a>, as it may not contain UTF-8, but
it does provide a method <ahref="type.AnsiByteString.html#method.write_to"><code>write_to</code></a> to write the result to any value that
</div></details><h2id="reexports"class="section-header">Re-exports<ahref="#reexports"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"id="reexport.Infix"><code>pub use ansi::<aclass="struct"href="ansi/struct.Infix.html"title="struct nu_ansi_term::ansi::Infix">Infix</a>;</code></div></li><li><divclass="item-name"id="reexport.Prefix"><code>pub use ansi::<aclass="struct"href="ansi/struct.Prefix.html"title="struct nu_ansi_term::ansi::Prefix">Prefix</a>;</code></div></li><li><divclass="item-name"id="reexport.Suffix"><code>pub use ansi::<aclass="struct"href="ansi/struct.Suffix.html"title="struct nu_ansi_term::ansi::Suffix">Suffix</a>;</code></div></li><li><divclass="item-name"><code>pub use <aclass="mod"href="gradient/index.html"title="mod nu_ansi_term::gradient">gradient</a>::*;</code></div></li></ul><h2id="modules"class="section-header">Modules<ahref="#modules"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="mod"href="ansi/index.html"title="mod nu_ansi_term::ansi">ansi</a></div></li><li><divclass="item-name"><aclass="mod"href="gradient/index.html"title="mod nu_ansi_term::gradient">gradient</a></div></li></ul><h2id="structs"class="section-header">Structs<ahref="#structs"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="struct"href="struct.AnsiGenericString.html"title="struct nu_ansi_term::AnsiGenericString">AnsiGenericString</a></div><divclass="desc docblock-short">An <code>AnsiGenericString</code> includes a generic string type and a <code>Style</code> to
display that string. <code>AnsiString</code> and <code>AnsiByteString</code> are aliases for
this type on <code>str</code> and <code>\[u8]</code>, respectively.</div></li><li><divclass="item-name"><aclass="struct"href="struct.AnsiGenericStrings.html"title="struct nu_ansi_term::AnsiGenericStrings">AnsiGenericStrings</a></div><divclass="desc docblock-short">A set of <code>AnsiGenericStrings</code>s collected together, in order to be
written with a minimum of control characters.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Rgb.html"title="struct nu_ansi_term::Rgb">Rgb</a></div></li><li><divclass="item-name"><aclass="struct"href="struct.Style.html"title="struct nu_ansi_term::Style">Style</a></div><divclass="desc docblock-short">A style is a collection of properties that can format a string
using ANSI escape codes.</div></li></ul><h2id="enums"class="section-header">Enums<ahref="#enums"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="enum"href="enum.Color.html"title="enum nu_ansi_term::Color">Color</a></div><divclass="desc docblock-short">A color is one specific type of ANSI escape code, and can refer
to either the foreground or background color.</div></li></ul><h2id="functions"class="section-header">Functions<ahref="#functions"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="fn"href="fn.AnsiByteStrings.html"title="fn nu_ansi_term::AnsiByteStrings">AnsiByteStrings</a></div><divclass="desc docblock-short">A function to construct an <code>AnsiByteStrings</code> instance.</div></li><li><divclass="item-name"><aclass="fn"href="fn.AnsiStrings.html"title="fn nu_ansi_term::AnsiStrings">AnsiStrings</a></div><divclass="desc docblock-short">A function to construct an <code>AnsiStrings</code> instance.</div></li><li><divclass="item-name"><aclass="fn"href="fn.sub_string.html"title="fn nu_ansi_term::sub_string">sub_string</a></div><divclass="desc docblock-short">Return a substring of the given AnsiStrings sequence, while keeping the formatting.</div></li><li><divclass="item-name"><aclass="fn"href="fn.unstyle.html"title="fn nu_ansi_term::unstyle">unstyle</a></div><divclass="desc docblock-short">Return a concatenated copy of <code>strs</code> without the formatting, as an allocated <code>String</code>.</div></li><li><divclass="item-name"><aclass="fn"href="fn.unstyled_len.html"title="fn nu_ansi_term::unstyled_len">unstyled_len</a></div><divclass="desc docblock-short">Return the unstyled length of AnsiStrings. This is equaivalent to <code>unstyle(strs).len()</code>.</div></li></ul><h2id="types"class="section-header">Type Aliases<ahref="#types"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="type"href="type.AnsiByteString.html"title="type nu_ansi_term::AnsiByteString">AnsiByteString</a></div><divclass="desc docblock-short">An <code>AnsiByteString</code> represents a formatted series of bytes. Use
<code>AnsiByteString</code> when styling text with an unknown encoding.</div></li><li><divclass="item-name"><aclass="type"href="type.AnsiByteStrings.html"title="type nu_ansi_term::AnsiByteStrings">AnsiByteStrings</a></div><divclass="desc docblock-short">A set of <code>AnsiByteString</code>s collected together, in order to be
written with a minimum of control characters.</div></li><li><divclass="item-name"><aclass="type"href="type.AnsiString.html"title="type nu_ansi_term::AnsiString">AnsiString</a></div><divclass="desc docblock-short">An ANSI String is a string coupled with the <code>Style</code> to display it
in a terminal.</div></li><li><divclass="item-name"><aclass="type"href="type.AnsiStrings.html"title="type nu_ansi_term::AnsiStrings">AnsiStrings</a></div><divclass="desc docblock-short">A set of <code>AnsiString</code>s collected together, in order to be written with a
minimum of control characters.</div></li></ul></section></div></main></body></html>
