xorfilter/
lib.rs

1//! Library implements xor-filter.
2//!
3//! Provides hasher types:
4//!
5//! * [NoHash], to be used when hash feature is not needed on [Xor8], [Fuse8] and
6//!   [Fuse16] types. Note that type methods that accept parametrized key cannot be
7//!   used.
8//! * [BuildHasherDefault] is the default hasher when `H` is not supplied. Note that
9//!   [DefaultHasher] uses an unspecified internal algorithm and so its hashes should
10//!   not be relied upon over releases.
11//!
12//! Refer to original implementation under `github.com/FastFilter` to learn the
13//! differences between [Xor8], [Fuse8] and [Fuse16] filters. Otherwise, all the types
14//! provides similar methods.
15//!
16//! **Handling duplicates**
17//!
18//! * [Fuse16] and [Xor8] implementation uses BTreeMap to make sure all the digests
19//!   generated from keys are unique, this avoids duplicates but decreases the build
20//!   performance significantly.
21//! * [Fuse8] implementation computes duplicates on the fly leading to significantly
22//!   better build performance. On the other hand, Fuse8 cannot handle more than
23//!   few duplicates.
24//!
25//! This is ported from its original implementation:
26//!
27//! * [Xor8] from <https://github.com/FastFilter/xorfilter>, written in golang.
28//! * [Fuse8] and [Fuse16] from <https://github.com/FastFilter/xor_singleheader>  written in C.
29
30#[allow(unused_imports)]
31use std::collections::hash_map::DefaultHasher;
32use std::{error, fmt, result};
33
34/// Short form to compose Error values.
35///
36/// Here are few possible ways:
37///
38/// ```ignore
39/// use crate::Error;
40/// err_at!(ParseError, msg: format!("bad argument"));
41/// ```
42///
43/// ```ignore
44/// use crate::Error;
45/// err_at!(ParseError, std::io::read(buf));
46/// ```
47///
48/// ```ignore
49/// use crate::Error;
50/// err_at!(ParseError, std::fs::read(file_path), format!("read failed"));
51/// ```
52///
53macro_rules! err_at {
54    ($v:ident, msg: $($arg:expr),+) => {{
55        let prefix = format!("{}:{}", file!(), line!());
56        Err(Error::$v(prefix, format!($($arg),+)))
57    }};
58    ($v:ident, $e:expr) => {{
59        match $e {
60            Ok(val) => Ok(val),
61            Err(err) => {
62                let prefix = format!("{}:{}", file!(), line!());
63                Err(Error::$v(prefix, format!("{}", err)))
64            }
65        }
66    }};
67    ($v:ident, $e:expr, $($arg:expr),+) => {{
68        match $e {
69            Ok(val) => Ok(val),
70            Err(err) => {
71                let prefix = format!("{}:{}", file!(), line!());
72                let msg = format!($($arg),+);
73                Err(Error::$v(prefix, format!("{} {}", err, msg)))
74            }
75        }
76    }};
77}
78
79/// Error variants that are returned by this package's API.
80///
81/// Each variant carries a prefix, typically identifying the
82/// error location.
83pub enum Error {
84    Fatal(String, String),
85}
86
87impl fmt::Display for Error {
88    fn fmt(&self, f: &mut fmt::Formatter) -> result::Result<(), fmt::Error> {
89        use Error::*;
90
91        match self {
92            Fatal(p, msg) => write!(f, "{} Fatal: {}", p, msg),
93        }
94    }
95}
96
97impl fmt::Debug for Error {
98    fn fmt(&self, f: &mut fmt::Formatter) -> result::Result<(), fmt::Error> {
99        write!(f, "{}", self)
100    }
101}
102
103impl error::Error for Error {}
104
105/// Type alias for Result return type, used by this package.
106pub type Result<T> = result::Result<T, Error>;
107
108mod fuse16;
109mod fuse8;
110mod hasher;
111mod xor8;
112
113pub use fuse16::Fuse16;
114pub use fuse8::Fuse8;
115pub use hasher::{BuildHasherDefault, NoHash};
116pub use xor8::Xor8;
xorfilter/lib.rs

xorfilter/
lib.rs
