fst_incremental 1.0.0

A thread-safe, updatable finite state set: dynamic insertions, deletions and queries over an immutable fst::Set fronted by a compact mutation buffer with amortized rebuilds.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

//! An updatable finite state set.
//!
//! [`fst::Set`] is compact and fast to query but immutable once built. [`IncrementalFstSet`]
//! keeps one of those as its persisted component and puts a sorted in-memory mutation buffer
//! in front of it. Inserts and removes land in the buffer; reads merge the two, so a query
//! always reflects the current logical state. When the buffer grows past a configured
//! threshold the two are merged into a fresh FST and the buffer is cleared.
//!
//! Removal from the persisted component is a tombstone rather than an erasure, which is why
//! deletions have their own rebuild threshold.
//!
//! # Persistence
//!
//! This crate performs no file I/O on its own behalf. A set's full state is two pieces, and
//! writing them is the caller's job:
//!
//! - the FST bytes, from [`IncrementalFstSet::persisted_fst_as_bytes`]
//! - the pending mutations, from [`IncrementalFstSet::buffers_snapshot`]
//!
//! Every mutating call returns an [`FstMutationResult`] saying which of the two changed, so
//! a caller can skip rewriting the FST when only the buffer moved.
//!
//! ```
//! use fst_incremental::{IncrementalFstSet, FstChangeType};
//!
//! let set = IncrementalFstSet::new(None)?;
//! set.insert(b"apple".to_vec())?;
//! set.insert(b"apricot".to_vec())?;
//! assert!(set.contains(b"apple")?);
//!
//! set.remove(b"apple")?;
//! assert!(!set.contains(b"apple")?);
//!
//! assert_eq!(set.force_rebuild()?.change_type, FstChangeType::FstRebuilt);
//! # Ok::<(), fst_incremental::IncrementalFstError>(())
//! ```
//!
//! # Features
//!
//! - `serde` (default): derives `Serialize` and `Deserialize` on [`SerializableFstBuffers`]
//!   and [`CompactArenaSet`] so the buffer can be persisted with a format of your choosing.

#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct Readme;

#[cfg(all(doctest, feature = "serde"))]
#[doc = include_str!("../README.USAGE.md")]
struct UsageGuide;

pub use fst;

mod arena;
mod error;
mod inner;
mod metrics;
mod set;
mod stream;
mod types;

pub use arena::CompactArenaSet;
pub use error::{IncrementalFstError, Result};
pub use metrics::FstMetricsSnapshot;
pub use set::IncrementalFstSet;
pub use stream::MergedSetStreamOwner;
pub use types::{FstChangeType, FstConfigOptions, FstMutationResult, SerializableFstBuffers};