1# strsim-rs
2
3[![Crates.io](https://img.shields.io/crates/v/strsim.svg)](https://crates.io/crates/strsim)
4[![Crates.io](https://img.shields.io/crates/l/strsim.svg?maxAge=2592000)](https://github.com/dguo/strsim-rs/blob/master/LICENSE)
5[![CI status](https://github.com/dguo/strsim-rs/workflows/CI/badge.svg)](https://github.com/dguo/strsim-rs/actions?query=branch%3Amaster)
6[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
7
8[Rust](https://www.rust-lang.org) implementations of [string similarity metrics]:
9  - [Hamming]
10  - [Levenshtein] - distance & normalized
11  - [Optimal string alignment]
12  - [Damerau-Levenshtein] - distance & normalized
13  - [Jaro and Jaro-Winkler] - this implementation of Jaro-Winkler does not limit the common prefix length
14
15The normalized versions return values between `0.0` and `1.0`, where `1.0` means
16an exact match.
17
18There are also generic versions of the functions for non-string inputs.
19
20## Installation
21
22`strsim` is available on [crates.io](https://crates.io/crates/strsim). Add it to
23your `Cargo.toml`:
24```toml
25[dependencies]
26strsim = "0.9.3"
27```
28
29## Usage
30
31Go to [Docs.rs](https://docs.rs/strsim/) for the full documentation. You can
32also clone the repo, and run `$ cargo doc --open`.
33
34### Examples
35
36```rust
37extern crate strsim;
38
39use strsim::{hamming, levenshtein, normalized_levenshtein, osa_distance,
40             damerau_levenshtein, normalized_damerau_levenshtein, jaro,
41             jaro_winkler};
42
43fn main() {
44    match hamming("hamming", "hammers") {
45        Ok(distance) => assert_eq!(3, distance),
46        Err(why) => panic!("{:?}", why)
47    }
48
49    assert_eq!(levenshtein("kitten", "sitting"), 3);
50
51    assert!((normalized_levenshtein("kitten", "sitting") - 0.571).abs() < 0.001);
52
53    assert_eq!(osa_distance("ac", "cba"), 3);
54
55    assert_eq!(damerau_levenshtein("ac", "cba"), 2);
56
57    assert!((normalized_damerau_levenshtein("levenshtein", "löwenbräu") - 0.272).abs() <
58            0.001);
59
60    assert!((jaro("Friedrich Nietzsche", "Jean-Paul Sartre") - 0.392).abs() <
61            0.001);
62
63    assert!((jaro_winkler("cheeseburger", "cheese fries") - 0.911).abs() <
64            0.001);
65}
66```
67
68Using the generic versions of the functions:
69
70```rust
71extern crate strsim;
72
73use strsim::generic_levenshtein;
74
75fn main() {
76    assert_eq!(2, generic_levenshtein(&[1, 2, 3], &[0, 2, 5]));
77}
78```
79
80## Contributing
81
82If you don't want to install Rust itself, you can run `$ ./dev` for a
83development CLI if you have [Docker] installed.
84
85Benchmarks require a Nightly toolchain. Run `$ cargo +nightly bench`.
86
87## License
88
89[MIT](https://github.com/dguo/strsim-rs/blob/master/LICENSE)
90
91[string similarity metrics]:http://en.wikipedia.org/wiki/String_metric
92[Damerau-Levenshtein]:http://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance
93[Jaro and Jaro-Winkler]:http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance
94[Levenshtein]:http://en.wikipedia.org/wiki/Levenshtein_distance
95[Hamming]:http://en.wikipedia.org/wiki/Hamming_distance
96[Optimal string alignment]:https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance#Optimal_string_alignment_distance
97[Docker]:https://docs.docker.com/engine/installation/
98