<!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="API documentation for the Rust `compare` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, compare">
<title>compare - Rust</title>
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../main.css">
</head>
<body class="rustdoc">
<nav class="sidebar">
<p class='location'></p><script>window.sidebarCurrent = {name: 'compare', ty: 'mod', relpath: '../'};</script>
</nav>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content mod">
<h1 class='fqn'><span class='in-band'>Crate <a class='mod' href=''>compare</a></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'>−</span>]
</a>
</span><a id='src-0' class='srclink' href='../src/compare/lib.rs.html#1-530' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>Comparators.</p>
<p>A comparator is any type that implements the <a href="trait.Compare.html"><code>Compare</code></a> trait,
which imposes a <a href="https://en.wikipedia.org/wiki/Total_order">total order</a>. Its
<a href="trait.Compare.html#tymethod.compare"><code>compare</code></a> method accepts two values, which may
be of the same type or different types, and returns an ordering on them.</p>
<p>Comparators are useful for parameterizing the behavior of sort methods and certain
data structures.</p>
<p>The most basic comparator is <a href="struct.Natural.html"><code>Natural</code></a>, which simply delegates
to the type's implementation of <a href="http://doc.rust-lang.org/std/cmp/trait.Ord.html"><code>Ord</code></a>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>compare</span>::{<span class='ident'>Compare</span>, <span class='ident'>natural</span>};
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>cmp</span>::<span class='ident'>Ordering</span>::{<span class='ident'>Less</span>, <span class='ident'>Equal</span>, <span class='ident'>Greater</span>};
<span class='kw'>let</span> <span class='ident'>a</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='number'>1</span>;
<span class='kw'>let</span> <span class='ident'>b</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='number'>2</span>;
<span class='kw'>let</span> <span class='ident'>cmp</span> <span class='op'>=</span> <span class='ident'>natural</span>();
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compare</span>(<span class='ident'>a</span>, <span class='ident'>b</span>), <span class='ident'>Less</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compare</span>(<span class='ident'>b</span>, <span class='ident'>a</span>), <span class='ident'>Greater</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compare</span>(<span class='ident'>a</span>, <span class='ident'>a</span>), <span class='ident'>Equal</span>);</pre>
<p>There are convenience methods for checking each of the six relations:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>compare</span>::{<span class='ident'>Compare</span>, <span class='ident'>natural</span>};
<span class='kw'>let</span> <span class='ident'>a</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='number'>1</span>;
<span class='kw'>let</span> <span class='ident'>b</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='number'>2</span>;
<span class='kw'>let</span> <span class='ident'>cmp</span> <span class='op'>=</span> <span class='ident'>natural</span>();
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compares_lt</span>(<span class='ident'>a</span>, <span class='ident'>b</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compares_le</span>(<span class='ident'>a</span>, <span class='ident'>b</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compares_ge</span>(<span class='ident'>b</span>, <span class='ident'>a</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compares_gt</span>(<span class='ident'>b</span>, <span class='ident'>a</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compares_eq</span>(<span class='ident'>a</span>, <span class='ident'>a</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compares_ne</span>(<span class='ident'>a</span>, <span class='ident'>b</span>));</pre>
<p>The <code>Compare</code> trait also provides default methods that
consume a comparator to produce a new one with different behavior, similar to
<a href="http://doc.rust-lang.org/std/iter/trait.IteratorExt.html">iterator adaptors</a>. For
example, all comparators can be <a href="trait.Compare.html#method.rev">reversed</a>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>compare</span>::{<span class='ident'>Compare</span>, <span class='ident'>natural</span>};
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>cmp</span>::<span class='ident'>Ordering</span>::<span class='ident'>Greater</span>;
<span class='kw'>let</span> <span class='ident'>cmp</span> <span class='op'>=</span> <span class='ident'>natural</span>().<span class='ident'>rev</span>();
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compare</span>(<span class='kw-2'>&</span><span class='number'>1</span>, <span class='kw-2'>&</span><span class='number'>2</span>), <span class='ident'>Greater</span>);</pre>
<p>It is possible to implement a comparator that is not based on the natural ordering of
a type by using a closure of type <code>Fn(&L, &R) -> Ordering</code>. For example, slices
can be compared by their length instead of their contents:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>compare</span>::<span class='ident'>Compare</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>cmp</span>::<span class='ident'>Ordering</span>::{<span class='ident'>Less</span>, <span class='ident'>Greater</span>};
<span class='kw'>let</span> <span class='ident'>a</span> <span class='op'>=</span> [<span class='number'>1</span>, <span class='number'>2</span>, <span class='number'>3</span>];
<span class='kw'>let</span> <span class='ident'>b</span> <span class='op'>=</span> [<span class='number'>4</span>, <span class='number'>5</span>];
<span class='kw'>let</span> <span class='ident'>cmp</span> <span class='op'>=</span> <span class='op'>|</span><span class='ident'>l</span>: <span class='kw-2'>&</span>[<span class='ident'>i32</span>], <span class='ident'>r</span>: <span class='kw-2'>&</span>[<span class='ident'>i32</span>]<span class='op'>|</span> <span class='ident'>l</span>.<span class='ident'>len</span>().<span class='ident'>cmp</span>(<span class='kw-2'>&</span><span class='ident'>r</span>.<span class='ident'>len</span>());
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compare</span>(<span class='kw-2'>&</span><span class='ident'>a</span>, <span class='kw-2'>&</span><span class='ident'>b</span>), <span class='ident'>Greater</span>);
<span class='kw'>let</span> <span class='ident'>cmp</span> <span class='op'>=</span> <span class='ident'>cmp</span>.<span class='ident'>rev</span>();
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cmp</span>.<span class='ident'>compare</span>(<span class='kw-2'>&</span><span class='ident'>a</span>, <span class='kw-2'>&</span><span class='ident'>b</span>), <span class='ident'>Less</span>);</pre>
<p>Comparators can be combined <a href="https://en.wikipedia.org/wiki/Lexicographical_order">lexicographically</a> in order to compare values
first by one key, <a href="trait.Compare.html#method.then">then</a>, if the first keys were
equal, by another:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>compare</span>::<span class='ident'>Compare</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>cmp</span>::<span class='ident'>Ordering</span>::{<span class='ident'>Less</span>, <span class='ident'>Equal</span>, <span class='ident'>Greater</span>};
<span class='kw'>struct</span> <span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='kw-2'>&</span><span class='lifetime'>'static</span> <span class='ident'>str</span>, <span class='ident'>age</span>: <span class='ident'>u8</span> }
<span class='kw'>let</span> <span class='ident'>fido4</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='string'>"Fido"</span>, <span class='ident'>age</span>: <span class='number'>4</span> };
<span class='kw'>let</span> <span class='ident'>ruff2</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='string'>"Ruff"</span>, <span class='ident'>age</span>: <span class='number'>2</span> };
<span class='kw'>let</span> <span class='ident'>fido3</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='string'>"Fido"</span>, <span class='ident'>age</span>: <span class='number'>3</span> };
<span class='kw'>let</span> <span class='ident'>name_cmp</span> <span class='op'>=</span> <span class='op'>|</span><span class='ident'>l</span>: <span class='kw-2'>&</span><span class='ident'>Pet</span>, <span class='ident'>r</span>: <span class='kw-2'>&</span><span class='ident'>Pet</span><span class='op'>|</span> <span class='ident'>l</span>.<span class='ident'>name</span>.<span class='ident'>cmp</span>(<span class='ident'>r</span>.<span class='ident'>name</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>ruff2</span>), <span class='ident'>Less</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>fido3</span>), <span class='ident'>Equal</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>ruff2</span>, <span class='ident'>fido3</span>), <span class='ident'>Greater</span>);
<span class='kw'>let</span> <span class='ident'>age_cmp</span> <span class='op'>=</span> <span class='op'>|</span><span class='ident'>l</span>: <span class='kw-2'>&</span><span class='ident'>Pet</span>, <span class='ident'>r</span>: <span class='kw-2'>&</span><span class='ident'>Pet</span><span class='op'>|</span> <span class='ident'>l</span>.<span class='ident'>age</span>.<span class='ident'>cmp</span>(<span class='kw-2'>&</span><span class='ident'>r</span>.<span class='ident'>age</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>ruff2</span>), <span class='ident'>Greater</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>fido3</span>), <span class='ident'>Greater</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>ruff2</span>, <span class='ident'>fido3</span>), <span class='ident'>Less</span>);
<span class='kw'>let</span> <span class='ident'>name_age_cmp</span> <span class='op'>=</span> <span class='ident'>name_cmp</span>.<span class='ident'>then</span>(<span class='ident'>age_cmp</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>ruff2</span>), <span class='ident'>Less</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>fido3</span>), <span class='ident'>Greater</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>ruff2</span>, <span class='ident'>fido3</span>), <span class='ident'>Greater</span>);</pre>
<p>It is often repetitive to compare two values of the same type by the same key, so the
<a href="struct.Extract.html">key-extraction logic</a> can be factored out, simplifying the
previous example:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>compare</span>::{<span class='ident'>Compare</span>, <span class='ident'>Extract</span>};
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>cmp</span>::<span class='ident'>Ordering</span>::{<span class='ident'>Less</span>, <span class='ident'>Greater</span>};
<span class='kw'>struct</span> <span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='kw-2'>&</span><span class='lifetime'>'static</span> <span class='ident'>str</span>, <span class='ident'>age</span>: <span class='ident'>u8</span> }
<span class='kw'>let</span> <span class='ident'>fido4</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='string'>"Fido"</span>, <span class='ident'>age</span>: <span class='number'>4</span> };
<span class='kw'>let</span> <span class='ident'>ruff2</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='string'>"Ruff"</span>, <span class='ident'>age</span>: <span class='number'>2</span> };
<span class='kw'>let</span> <span class='ident'>fido3</span> <span class='op'>=</span> <span class='kw-2'>&</span><span class='ident'>Pet</span> { <span class='ident'>name</span>: <span class='string'>"Fido"</span>, <span class='ident'>age</span>: <span class='number'>3</span> };
<span class='kw'>let</span> <span class='ident'>name_age_cmp</span> <span class='op'>=</span> <span class='ident'>Extract</span>::<span class='ident'>new</span>(<span class='op'>|</span><span class='ident'>p</span>: <span class='kw-2'>&</span><span class='ident'>Pet</span><span class='op'>|</span> <span class='ident'>p</span>.<span class='ident'>name</span>)
.<span class='ident'>then</span>(<span class='ident'>Extract</span>::<span class='ident'>new</span>(<span class='op'>|</span><span class='ident'>p</span>: <span class='kw-2'>&</span><span class='ident'>Pet</span><span class='op'>|</span> <span class='ident'>p</span>.<span class='ident'>age</span>));
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>ruff2</span>), <span class='ident'>Less</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>fido4</span>, <span class='ident'>fido3</span>), <span class='ident'>Greater</span>);
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>name_age_cmp</span>.<span class='ident'>compare</span>(<span class='ident'>ruff2</span>, <span class='ident'>fido3</span>), <span class='ident'>Greater</span>);</pre>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class='struct' href='struct.Borrowing.html'
title='compare::Borrowing'>Borrowing</a></td>
<td class='docblock short'>
<p>A comparator that borrows its parameters before comparing them.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Extract.html'
title='compare::Extract'>Extract</a></td>
<td class='docblock short'>
<p>A comparator that extracts a sort key from a value.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Natural.html'
title='compare::Natural'>Natural</a></td>
<td class='docblock short'>
<p>A comparator that delegates to <a href="http://doc.rust-lang.org/std/cmp/trait.Ord.html"><code>Ord</code></a>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Rev.html'
title='compare::Rev'>Rev</a></td>
<td class='docblock short'>
<p>A comparator that reverses the ordering of another.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Swap.html'
title='compare::Swap'>Swap</a></td>
<td class='docblock short'>
<p>A comparator that swaps another's parameters, maintaining the underlying ordering.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Then.html'
title='compare::Then'>Then</a></td>
<td class='docblock short'>
<p>A comparator that <a href="https://en.wikipedia.org/wiki/Lexicographical_order">lexicographically</a> combines two others.</p>
</td>
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table>
<tr class=' module-item'>
<td><a class='trait' href='trait.Compare.html'
title='compare::Compare'>Compare</a></td>
<td class='docblock short'>
<p>A comparator imposing a <a href="https://en.wikipedia.org/wiki/Total_order">total order</a>.</p>
</td>
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
<tr class=' module-item'>
<td><a class='fn' href='fn.max.html'
title='compare::max'>max</a></td>
<td class='docblock short'>
<p>Returns the maximum of two values according to the given comparator, or <code>r</code> if they
are equal.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='fn' href='fn.min.html'
title='compare::min'>min</a></td>
<td class='docblock short'>
<p>Returns the minimum of two values according to the given comparator, or <code>l</code> if they
are equal.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='fn' href='fn.natural.html'
title='compare::natural'>natural</a></td>
<td class='docblock short'>
<p>Returns a comparator that delegates to <code>Ord</code>.</p>
</td>
</tr></table></section>
<section id='search' class="content hidden"></section>
<section class="footer"></section>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt>?</dt>
<dd>Show this help dialog</dd>
<dt>S</dt>
<dd>Focus the search field</dd>
<dt>⇤</dt>
<dd>Move up in search results</dd>
<dt>⇥</dt>
<dd>Move down in search results</dd>
<dt>⏎</dt>
<dd>Go to active search result</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "compare";
window.playgroundUrl = "";
</script>
<script src="../jquery.js"></script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>