rust/tantivy
1
0
Fork 0
mirror of https://github.com/quickwit-oss/tantivy.git synced 2026-05-20 10:10:42 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c9fcdeb54e2013b5ff3c7f0095b06ccda2e032ed
tantivy/master/fst/struct.Map.html
Travis CI User 958783759a Automatic Travis documentation build
2018-04-10 01:26:48 +00:00

382 lines
48 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="API documentation for the Rust `Map` struct in crate `fst`.">
<meta name="keywords" content="rust, rustlang, rust-lang, Map">
<title>fst::Map - Rust</title>
<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="../dark.css">
<link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle">
<script src="../storage.js"></script>
</head>
<body class="rustdoc struct">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<div class="sidebar-menu">&#9776;</div>
<p class='location'>Struct Map</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.from_path">from_path</a><a href="#method.from_bytes">from_bytes</a><a href="#method.from_iter">from_iter</a><a href="#method.contains_key">contains_key</a><a href="#method.get">get</a><a href="#method.stream">stream</a><a href="#method.keys">keys</a><a href="#method.values">values</a><a href="#method.range">range</a><a href="#method.search">search</a><a href="#method.len">len</a><a href="#method.is_empty">is_empty</a><a href="#method.op">op</a><a href="#method.as_fst">as_fst</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Debug">Debug</a><a href="#impl-From%3CFst%3E">From&lt;Fst&gt;</a><a href="#impl-AsRef%3CFst%3E">AsRef&lt;Fst&gt;</a><a href="#impl-IntoStreamer%3C%27a%3E">IntoStreamer&lt;&#39;a&gt;</a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-Send">Send</a><a href="#impl-Sync">Sync</a></div></div><p class='location'><a href='index.html'>fst</a></p><script>window.sidebarCurrent = {name: 'Map', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></script></div>
</nav>
<div class="theme-picker">
<button id="theme-picker" aria-label="Pick another theme!">
<img src="../brush.svg" width="18" alt="Pick another theme!">
</button>
<div id="theme-choices"></div>
</div>
<script src="../theme.js"></script>
<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"><h1 class='fqn'><span class='in-band'>Struct <a href='index.html'>fst</a>::<wbr><a class="struct" href=''>Map</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'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../src/fst/map.rs.html#57' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><pre class='rust struct'>pub struct Map(_);</pre></div><div class='docblock'><p>Map is a lexicographically ordered map from byte strings to integers.</p>
<p>A <code>Map</code> is constructed with the <code>MapBuilder</code> type. Alternatively, a <code>Map</code>
can be constructed in memory from a lexicographically ordered iterator
of key-value pairs (<code>Map::from_iter</code>).</p>
<p>A key feature of <code>Map</code> is that it can be serialized to disk compactly. Its
underlying representation is built such that the <code>Map</code> can be memory mapped
(<code>Map::from_path</code>) and searched without necessarily loading the entire
map into memory.</p>
<p>It supports most common operations associated with maps, such as key
lookup and search. It also supports set operations on its keys along with
the ability to specify how conflicting values are merged together. Maps
also support range queries and automata based searches (e.g. a regular
expression).</p>
<p>Maps are represented by a finite state transducer where inputs are the keys
and outputs are the values. As such, maps have the following invariants:</p>
<ol>
<li>Once constructed, a <code>Map</code> can never be modified.</li>
<li>Maps must be constructed with lexicographically ordered byte sequences.
There is no restricting on the ordering of values.</li>
</ol>
<h1 id="differences-with-sets" class="section-header"><a href="#differences-with-sets">Differences with sets</a></h1>
<p>Maps and sets are represented by the same underlying data structure: the
finite state transducer. The principal difference between them is that
sets always have their output values set to <code>0</code>. This has an impact on the
representation size and is reflected in the type system for convenience.
A secondary but subtle difference is that duplicate values can be added
to a set, but it is an error to do so with maps. That is, a set can have
the same key added sequentially, but a map can't.</p>
<h1 id="the-future" class="section-header"><a href="#the-future">The future</a></h1>
<p>It is regrettable that the output value is fixed to <code>u64</code>. Indeed, it is
not necessary, but it was a major simplification in the implementation.
In the future, the value type may become generic to an extent (outputs must
satisfy a basic algebra).</p>
<p>Keys will always be byte strings; however, we may grow more conveniences
around dealing with them (such as a serialization/deserialization step,
although it isn't clear where exactly this should live).</p>
</div>
<h2 id='methods' class='small-section-header'>
Methods<a href='#methods' class='anchor'></a>
</h2>
<h3 id='impl' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#59-357' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.from_path' class="method"><span id='from_path.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.from_path' class='fnname'>from_path</a>&lt;P:&nbsp;<a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="struct" href="https://doc.rust-lang.org/nightly/std/path/struct.Path.html" title="struct std::path::Path">Path</a>&gt;&gt;(path: P) -&gt; <a class="type" href="../fst/type.Result.html" title="type fst::Result">Result</a>&lt;Self&gt;</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#67-69' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Opens a map stored at the given file path via a memory map.</p>
<p>The map must have been written with a compatible finite state
transducer builder (<code>MapBuilder</code> qualifies). If the format is invalid
or if there is a mismatch between the API version of this library
and the map, then an error is returned.</p>
</div><h4 id='method.from_bytes' class="method"><span id='from_bytes.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.from_bytes' class='fnname'>from_bytes</a>(bytes: <a class="struct" href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a>&gt;) -&gt; <a class="type" href="../fst/type.Result.html" title="type fst::Result">Result</a>&lt;Self&gt;</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#79-81' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Creates a map from its representation as a raw byte sequence.</p>
<p>Note that this operation is very cheap (no allocations and no copies).</p>
<p>The map must have been written with a compatible finite state
transducer builder (<code>MapBuilder</code> qualifies). If the format is invalid
or if there is a mismatch between the API version of this library
and the map, then an error is returned.</p>
</div><h4 id='method.from_iter' class="method"><span id='from_iter.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.from_iter' class='fnname'>from_iter</a>&lt;K, I&gt;(iter: I) -&gt; <a class="type" href="../fst/type.Result.html" title="type fst::Result">Result</a>&lt;Self&gt; <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;K: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>&gt;,<br>&nbsp;&nbsp;&nbsp;&nbsp;I: <a class="trait" href="https://doc.rust-lang.org/nightly/core/iter/traits/trait.IntoIterator.html" title="trait core::iter::traits::IntoIterator">IntoIterator</a>&lt;Item = <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a>K, <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">)</a>&gt;,&nbsp;</span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#92-97' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Create a <code>Map</code> from an iterator of lexicographically ordered byte
strings and associated values.</p>
<p>If the iterator does not yield unique keys in lexicographic order, then
an error is returned.</p>
<p>Note that this is a convenience function to build a map in memory.
To build a map that streams to an arbitrary <code>io::Write</code>, use
<code>MapBuilder</code>.</p>
</div><h4 id='method.contains_key' class="method"><span id='contains_key.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.contains_key' class='fnname'>contains_key</a>&lt;K:&nbsp;<a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>&gt;&gt;(&amp;self, key: K) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#111-113' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Tests the membership of a single key.</p>
<h1 id="example" class="section-header"><a href="#example">Example</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::<span class="ident">Map</span>;
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>)]).<span class="ident">unwrap</span>();
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">map</span>.<span class="ident">contains_key</span>(<span class="string">&quot;b&quot;</span>), <span class="bool-val">true</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">map</span>.<span class="ident">contains_key</span>(<span class="string">&quot;z&quot;</span>), <span class="bool-val">false</span>);</pre>
</div><h4 id='method.get' class="method"><span id='get.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.get' class='fnname'>get</a>&lt;K:&nbsp;<a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>&gt;&gt;(&amp;self, key: K) -&gt; <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a>&gt;</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#129-131' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Retrieves the value associated with a key.</p>
<p>If the key does not exist, then <code>None</code> is returned.</p>
<h1 id="example-1" class="section-header"><a href="#example-1">Example</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::<span class="ident">Map</span>;
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>)]).<span class="ident">unwrap</span>();
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">map</span>.<span class="ident">get</span>(<span class="string">&quot;b&quot;</span>), <span class="prelude-val">Some</span>(<span class="number">2</span>));
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">map</span>.<span class="ident">get</span>(<span class="string">&quot;z&quot;</span>), <span class="prelude-val">None</span>);</pre>
</div><h4 id='method.stream' class="method"><span id='stream.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.stream' class='fnname'>stream</a>(&amp;self) -&gt; <a class="struct" href="../fst/map/struct.Stream.html" title="struct fst::map::Stream">Stream</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#165-167' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Return a lexicographically ordered stream of all key-value pairs in
this map.</p>
<p>While this is a stream, it does require heap space proportional to the
longest key in the map.</p>
<p>If the map is memory mapped, then no further heap space is needed.
Note though that your operating system may fill your page cache
(which will cause the resident memory usage of the process to go up
correspondingly).</p>
<h1 id="example-2" class="section-header"><a href="#example-2">Example</a></h1>
<p>Since streams are not iterators, the traditional <code>for</code> loop cannot be
used. <code>while let</code> is useful instead:</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::{<span class="ident">IntoStreamer</span>, <span class="ident">Streamer</span>, <span class="ident">Map</span>};
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>)]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">map</span>.<span class="ident">stream</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">kvs</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">while</span> <span class="kw">let</span> <span class="prelude-val">Some</span>((<span class="ident">k</span>, <span class="ident">v</span>)) <span class="op">=</span> <span class="ident">stream</span>.<span class="ident">next</span>() {
<span class="ident">kvs</span>.<span class="ident">push</span>((<span class="ident">k</span>.<span class="ident">to_vec</span>(), <span class="ident">v</span>));
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">kvs</span>, <span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">b&quot;a&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">1</span>),
(<span class="string">b&quot;b&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">2</span>),
(<span class="string">b&quot;c&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">3</span>),
]);</pre>
</div><h4 id='method.keys' class="method"><span id='keys.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.keys' class='fnname'>keys</a>(&amp;self) -&gt; <a class="struct" href="../fst/map/struct.Keys.html" title="struct fst::map::Keys">Keys</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#187-189' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Return a lexicographically ordered stream of all keys in this map.</p>
<p>Memory requirements are the same as described on <code>Map::stream</code>.</p>
<h1 id="example-3" class="section-header"><a href="#example-3">Example</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::{<span class="ident">IntoStreamer</span>, <span class="ident">Streamer</span>, <span class="ident">Map</span>};
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>)]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">map</span>.<span class="ident">keys</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">keys</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">while</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">k</span>) <span class="op">=</span> <span class="ident">stream</span>.<span class="ident">next</span>() {
<span class="ident">keys</span>.<span class="ident">push</span>(<span class="ident">k</span>.<span class="ident">to_vec</span>());
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">keys</span>, <span class="macro">vec</span><span class="macro">!</span>[<span class="string">b&quot;a&quot;</span>, <span class="string">b&quot;b&quot;</span>, <span class="string">b&quot;c&quot;</span>]);</pre>
</div><h4 id='method.values' class="method"><span id='values.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.values' class='fnname'>values</a>(&amp;self) -&gt; <a class="struct" href="../fst/map/struct.Values.html" title="struct fst::map::Values">Values</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#210-212' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Return a stream of all values in this map ordered lexicographically
by each value's corresponding key.</p>
<p>Memory requirements are the same as described on <code>Map::stream</code>.</p>
<h1 id="example-4" class="section-header"><a href="#example-4">Example</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::{<span class="ident">IntoStreamer</span>, <span class="ident">Streamer</span>, <span class="ident">Map</span>};
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>)]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">map</span>.<span class="ident">values</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">values</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">while</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">v</span>) <span class="op">=</span> <span class="ident">stream</span>.<span class="ident">next</span>() {
<span class="ident">values</span>.<span class="ident">push</span>(<span class="ident">v</span>);
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">values</span>, <span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>]);</pre>
</div><h4 id='method.range' class="method"><span id='range.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.range' class='fnname'>range</a>(&amp;self) -&gt; <a class="struct" href="../fst/map/struct.StreamBuilder.html" title="struct fst::map::StreamBuilder">StreamBuilder</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#245-247' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Return a builder for range queries.</p>
<p>A range query returns a subset of key-value pairs in this map in a
range given in lexicographic order.</p>
<p>Memory requirements are the same as described on <code>Map::stream</code>.
Notably, only the keys in the range are read; keys outside the range
are not.</p>
<h1 id="example-5" class="section-header"><a href="#example-5">Example</a></h1>
<p>Returns only the key-value pairs in the range given.</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::{<span class="ident">IntoStreamer</span>, <span class="ident">Streamer</span>, <span class="ident">Map</span>};
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>), (<span class="string">&quot;d&quot;</span>, <span class="number">4</span>), (<span class="string">&quot;e&quot;</span>, <span class="number">5</span>),
]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">map</span>.<span class="ident">range</span>().<span class="ident">ge</span>(<span class="string">&quot;b&quot;</span>).<span class="ident">lt</span>(<span class="string">&quot;e&quot;</span>).<span class="ident">into_stream</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">kvs</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">while</span> <span class="kw">let</span> <span class="prelude-val">Some</span>((<span class="ident">k</span>, <span class="ident">v</span>)) <span class="op">=</span> <span class="ident">stream</span>.<span class="ident">next</span>() {
<span class="ident">kvs</span>.<span class="ident">push</span>((<span class="ident">k</span>.<span class="ident">to_vec</span>(), <span class="ident">v</span>));
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">kvs</span>, <span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">b&quot;b&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">2</span>),
(<span class="string">b&quot;c&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">3</span>),
(<span class="string">b&quot;d&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">4</span>),
]);</pre>
</div><h4 id='method.search' class="method"><span id='search.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.search' class='fnname'>search</a>&lt;A:&nbsp;<a class="trait" href="../fst/automaton/trait.Automaton.html" title="trait fst::automaton::Automaton">Automaton</a>&gt;(&amp;self, aut: A) -&gt; <a class="struct" href="../fst/map/struct.StreamBuilder.html" title="struct fst::map::StreamBuilder">StreamBuilder</a>&lt;A&gt;</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#292-294' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Executes an automaton on the keys of this map.</p>
<p>Note that this returns a <code>StreamBuilder</code>, which can be used to
add a range query to the search (see the <code>range</code> method).</p>
<p>Memory requirements are the same as described on <code>Map::stream</code>.</p>
<h1 id="example-6" class="section-header"><a href="#example-6">Example</a></h1>
<p>An implementation of regular expressions for <code>Automaton</code> is available
in the <code>fst-regex</code> crate, which can be used to search maps.</p>
<pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">fst</span>;
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">fst_regex</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">error</span>::<span class="ident">Error</span>;
<span class="kw">use</span> <span class="ident">fst</span>::{<span class="ident">IntoStreamer</span>, <span class="ident">Streamer</span>, <span class="ident">Map</span>};
<span class="kw">use</span> <span class="ident">fst_regex</span>::<span class="ident">Regex</span>;
<span class="kw">fn</span> <span class="ident">example</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">Box</span><span class="op">&lt;</span><span class="ident">Error</span><span class="op">&gt;&gt;</span> {
<span class="kw">let</span> <span class="ident">map</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">&quot;foo&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;foo1&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;foo2&quot;</span>, <span class="number">3</span>), (<span class="string">&quot;foo3&quot;</span>, <span class="number">4</span>), (<span class="string">&quot;foobar&quot;</span>, <span class="number">5</span>),
]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="ident">re</span> <span class="op">=</span> <span class="ident">Regex</span>::<span class="ident">new</span>(<span class="string">&quot;f[a-z]+3?&quot;</span>).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">stream</span> <span class="op">=</span> <span class="ident">map</span>.<span class="ident">search</span>(<span class="kw-2">&amp;</span><span class="ident">re</span>).<span class="ident">into_stream</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">kvs</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">while</span> <span class="kw">let</span> <span class="prelude-val">Some</span>((<span class="ident">k</span>, <span class="ident">v</span>)) <span class="op">=</span> <span class="ident">stream</span>.<span class="ident">next</span>() {
<span class="ident">kvs</span>.<span class="ident">push</span>((<span class="ident">k</span>.<span class="ident">to_vec</span>(), <span class="ident">v</span>));
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">kvs</span>, <span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">b&quot;foo&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">1</span>),
(<span class="string">b&quot;foo3&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">4</span>),
(<span class="string">b&quot;foobar&quot;</span>.<span class="ident">to_vec</span>(), <span class="number">5</span>),
]);
<span class="prelude-val">Ok</span>(())
}</pre>
</div><h4 id='method.len' class="method"><span id='len.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.len' class='fnname'>len</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#297-299' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Returns the number of elements in this map.</p>
</div><h4 id='method.is_empty' class="method"><span id='is_empty.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.is_empty' class='fnname'>is_empty</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#302-304' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Returns true if and only if this map is empty.</p>
</div><h4 id='method.op' class="method"><span id='op.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.op' class='fnname'>op</a>(&amp;self) -&gt; <a class="struct" href="../fst/map/struct.OpBuilder.html" title="struct fst::map::OpBuilder">OpBuilder</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#349-351' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Creates a new map operation with this map added to it.</p>
<p>The <code>OpBuilder</code> type can be used to add additional map streams
and perform set operations like union, intersection, difference and
symmetric difference on the keys of the map. These set operations also
allow one to specify how conflicting values are merged in the stream.</p>
<h1 id="example-7" class="section-header"><a href="#example-7">Example</a></h1>
<p>This example demonstrates a union on multiple map streams. Notice that
the stream returned from the union is not a sequence of key-value
pairs, but rather a sequence of keys associated with one or more
values. Namely, a key is associated with each value associated with
that same key in the all of the streams.</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">fst</span>::{<span class="ident">Streamer</span>, <span class="ident">Map</span>};
<span class="kw">use</span> <span class="ident">fst</span>::<span class="ident">map</span>::<span class="ident">IndexedValue</span>;
<span class="kw">let</span> <span class="ident">map1</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">&quot;a&quot;</span>, <span class="number">1</span>), (<span class="string">&quot;b&quot;</span>, <span class="number">2</span>), (<span class="string">&quot;c&quot;</span>, <span class="number">3</span>),
]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="ident">map2</span> <span class="op">=</span> <span class="ident">Map</span>::<span class="ident">from_iter</span>(<span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">&quot;a&quot;</span>, <span class="number">10</span>), (<span class="string">&quot;y&quot;</span>, <span class="number">11</span>), (<span class="string">&quot;z&quot;</span>, <span class="number">12</span>),
]).<span class="ident">unwrap</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">union</span> <span class="op">=</span> <span class="ident">map1</span>.<span class="ident">op</span>().<span class="ident">add</span>(<span class="kw-2">&amp;</span><span class="ident">map2</span>).<span class="ident">union</span>();
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">kvs</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[];
<span class="kw">while</span> <span class="kw">let</span> <span class="prelude-val">Some</span>((<span class="ident">k</span>, <span class="ident">vs</span>)) <span class="op">=</span> <span class="ident">union</span>.<span class="ident">next</span>() {
<span class="ident">kvs</span>.<span class="ident">push</span>((<span class="ident">k</span>.<span class="ident">to_vec</span>(), <span class="ident">vs</span>.<span class="ident">to_vec</span>()));
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">kvs</span>, <span class="macro">vec</span><span class="macro">!</span>[
(<span class="string">b&quot;a&quot;</span>.<span class="ident">to_vec</span>(), <span class="macro">vec</span><span class="macro">!</span>[
<span class="ident">IndexedValue</span> { <span class="ident">index</span>: <span class="number">0</span>, <span class="ident">value</span>: <span class="number">1</span> },
<span class="ident">IndexedValue</span> { <span class="ident">index</span>: <span class="number">1</span>, <span class="ident">value</span>: <span class="number">10</span> },
]),
(<span class="string">b&quot;b&quot;</span>.<span class="ident">to_vec</span>(), <span class="macro">vec</span><span class="macro">!</span>[<span class="ident">IndexedValue</span> { <span class="ident">index</span>: <span class="number">0</span>, <span class="ident">value</span>: <span class="number">2</span> }]),
(<span class="string">b&quot;c&quot;</span>.<span class="ident">to_vec</span>(), <span class="macro">vec</span><span class="macro">!</span>[<span class="ident">IndexedValue</span> { <span class="ident">index</span>: <span class="number">0</span>, <span class="ident">value</span>: <span class="number">3</span> }]),
(<span class="string">b&quot;y&quot;</span>.<span class="ident">to_vec</span>(), <span class="macro">vec</span><span class="macro">!</span>[<span class="ident">IndexedValue</span> { <span class="ident">index</span>: <span class="number">1</span>, <span class="ident">value</span>: <span class="number">11</span> }]),
(<span class="string">b&quot;z&quot;</span>.<span class="ident">to_vec</span>(), <span class="macro">vec</span><span class="macro">!</span>[<span class="ident">IndexedValue</span> { <span class="ident">index</span>: <span class="number">1</span>, <span class="ident">value</span>: <span class="number">12</span> }]),
]);</pre>
</div><h4 id='method.as_fst' class="method"><span id='as_fst.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.as_fst' class='fnname'>as_fst</a>(&amp;self) -&gt; &amp;<a class="struct" href="../fst/raw/struct.Fst.html" title="struct fst::raw::Fst">Fst</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#354-356' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Returns a reference to the underlying raw finite state transducer.</p>
</div></div>
<h2 id='implementations' class='small-section-header'>
Trait Implementations<a href='#implementations' class='anchor'></a>
</h2>
<div id='implementations-list'><h3 id='impl-Debug' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a> for <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl-Debug' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#359-373' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&amp;self, f: &amp;mut <a class="struct" href="https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>) -&gt; <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#360-372' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Formats the value using the given formatter. <a href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</div></div><h3 id='impl-From%3CFst%3E' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;<a class="struct" href="../fst/raw/struct.Fst.html" title="struct fst::raw::Fst">Fst</a>&gt; for <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl-From%3CFst%3E' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#376-380' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.from' class="method"><span id='from.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.From.html#tymethod.from' class='fnname'>from</a>(fst: <a class="struct" href="../fst/raw/struct.Fst.html" title="struct fst::raw::Fst">Fst</a>) -&gt; <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#377-379' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Performs the conversion.</p>
</div></div><h3 id='impl-AsRef%3CFst%3E' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="struct" href="../fst/raw/struct.Fst.html" title="struct fst::raw::Fst">Fst</a>&gt; for <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl-AsRef%3CFst%3E' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#383-387' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='docblock'><p>Returns the underlying finite state transducer.</p>
</div><div class='impl-items'><h4 id='method.as_ref' class="method"><span id='as_ref.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html#tymethod.as_ref' class='fnname'>as_ref</a>(&amp;self) -&gt; &amp;<a class="struct" href="../fst/raw/struct.Fst.html" title="struct fst::raw::Fst">Fst</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#384-386' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Performs the conversion.</p>
</div></div><h3 id='impl-IntoStreamer%3C%27a%3E' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl&lt;'m, 'a&gt; <a class="trait" href="../fst/trait.IntoStreamer.html" title="trait fst::IntoStreamer">IntoStreamer</a>&lt;'a&gt; for &amp;'m <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl-IntoStreamer%3C%27a%3E' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#389-396' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='associatedtype.Item' class="type"><span id='Item.t' class='invisible'><code>type <a href='../fst/trait.IntoStreamer.html#associatedtype.Item' class="type">Item</a> = <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&amp;'a [</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>, <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">)</a></code></span></h4>
<div class='docblock'><p>The type of the item emitted by the stream.</p>
</div><h4 id='associatedtype.Into' class="type"><span id='Into.t' class='invisible'><code>type <a href='../fst/trait.IntoStreamer.html#associatedtype.Into' class="type">Into</a> = <a class="struct" href="../fst/map/struct.Stream.html" title="struct fst::map::Stream">Stream</a>&lt;'m&gt;</code></span></h4>
<div class='docblock'><p>The type of the stream to be constructed.</p>
</div><h4 id='method.into_stream' class="method"><span id='into_stream.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='../fst/trait.IntoStreamer.html#tymethod.into_stream' class='fnname'>into_stream</a>(self) -&gt; Self::<a class="type" href="../fst/trait.IntoStreamer.html#associatedtype.Into" title="type fst::IntoStreamer::Into">Into</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../src/fst/map.rs.html#393-395' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Construct a stream from <code>Self</code>.</p>
</div></div></div>
<h2 id='synthetic-implementations' class='small-section-header'>
Auto Trait Implementations<a href='#synthetic-implementations' class='anchor'></a>
</h2>
<div id='synthetic-implementations-list'>
<h3 id='impl-Send' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> for <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl-Send' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></div><h3 id='impl-Sync' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a> for <a class="struct" href="../fst/struct.Map.html" title="struct fst::Map">Map</a></code><a href='#impl-Sync' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></div></div></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><kbd>?</kbd></dt>
<dd>Show this help dialog</dd>
<dt><kbd>S</kbd></dt>
<dd>Focus the search field</dd>
<dt><kbd>↑</kbd></dt>
<dd>Move up in search results</dd>
<dt><kbd>↓</kbd></dt>
<dd>Move down in search results</dd>
<dt><kbd>↹</kbd></dt>
<dd>Switch tab</dd>
<dt><kbd>&#9166;</kbd></dt>
<dd>Go to active search result</dd>
<dt><kbd>+</kbd></dt>
<dd>Expand all sections</dd>
<dt><kbd>-</kbd></dt>
<dd>Collapse all sections</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 = "fst";
</script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink