vendor/fst/README.md

   1 fst
   2 ===
   3 This crate provides a fast implementation of ordered sets and maps using finite
   4 state machines. In particular, it makes use of finite state transducers to map
   5 keys to values as the machine is executed. Using finite state machines as data
   6 structures enables us to store keys in a compact format that is also easily
   7 searchable. For example, this crate leverages memory maps to make range queries
   8 very fast.
   9
  10 Check out my blog post
  11 [Index 1,600,000,000 Keys with Automata and
  12 Rust](http://blog.burntsushi.net/transducers/)
  13 for extensive background, examples and experiments.
  14
  15 [![Build status](https://github.com/BurntSushi/fst/workflows/ci/badge.svg)](https://github.com/BurntSushi/fst/actions)
  16 [![](http://meritbadge.herokuapp.com/fst)](https://crates.io/crates/fst)
  17
  18 Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org).
  19
  20
  21 ### Documentation
  22
  23 https://docs.rs/fst
  24
  25 The
  26 [`regex-automata`](https://docs.rs/regex-automata)
  27 crate provides implementations of the `fst::Automata` trait when its
  28 `transducer` feature is enabled. This permits using DFAs compiled by
  29 `regex-automata` to search finite state transducers produced by this crate.
  30
  31
  32 ### Installation
  33
  34 Simply add a corresponding entry to your `Cargo.toml` dependency list:
  35
  36 ```toml,ignore
  37 [dependencies]
  38 fst = "0.4"
  39 ```
  40
  41
  42 ### Example
  43
  44 This example demonstrates building a set in memory and executing a fuzzy query
  45 against it. You'll need `fst = "0.4"` with the `levenshtein` feature enabled in
  46 your `Cargo.toml`.
  47
  48 ```rust
  49 use fst::{IntoStreamer, Set};
  50 use fst::automaton::Levenshtein;
  51
  52 fn main() -> Result<(), Box<dyn std::error::Error>> {
  53   // A convenient way to create sets in memory.
  54   let keys = vec!["fa", "fo", "fob", "focus", "foo", "food", "foul"];
  55   let set = Set::from_iter(keys)?;
  56
  57   // Build our fuzzy query.
  58   let lev = Levenshtein::new("foo", 1)?;
  59
  60   // Apply our fuzzy query to the set we built.
  61   let stream = set.search(lev).into_stream();
  62
  63   let keys = stream.into_strs()?;
  64   assert_eq!(keys, vec!["fo", "fob", "foo", "food"]);
  65   Ok(())
  66 }
  67 ```
  68
  69 Check out the documentation for a lot more examples!
  70
  71
  72 ### Cargo features
  73
  74 * `levenshtein` - **Disabled** by default. This adds the `Levenshtein`
  75   automaton to the `automaton` sub-module. This includes an additional
  76   dependency on `utf8-ranges`.