Examples & Tutorials

This directory holds the numbered tutorial series for liblevenshtein — a guided path from a first spell checker to a complete phonetic spellcheck application — plus an index of every runnable example in examples/. Each tutorial is grounded in a real, compiling example, so every snippet you read is copied or condensed from code you can run.

New to the library? Start with the main README for the conceptual overview (Levenshtein automata, the dictionary family, feature flags), then follow the tutorials below in order.

---

Tutorial series

A progressive, eight-part walkthrough. Each part explains one concept, walks through its backing example in a few annotated snippets, gives the exact cargo run command, and embeds the relevant architecture diagrams.

#	Tutorial	You'll learn	Backing example
01	Getting Started	Build a spell checker from a dictionary + algorithm + transducer; query vs query_with_distance	spell_checker.rs
02	Dictionaries	Pick a backend for your access pattern; mutate a DynamicDawg at runtime; serialize to disk	dynamic_dictionary.rs, serialization.rs
03	Algorithms & Ordering	Standard / Transposition / MergeAndSplit; distance-first ordered results and lazy top-$k$	ordered_query_demo.rs
04	Queries & Unicode	Unicode matching and zero-cost custom substitutions (diacritics, case-folding, kana)	unicode_diacritics.rs
05	Values & Fuzzy Maps	Attach values to terms; filter, prioritize, and prune by value during traversal	fuzzy_maps_code_completion.rs
06	Contextual Completion	Incremental drafts, checkpoints/undo, and hierarchical scope visibility	contextual_completion.rs
07	Performance & Concurrency	Benchmark on a real 124k-word dictionary; backend trade-offs; the lock-free read model	real_world_benchmark.rs
08	Real-World: Phonetic Spellcheck	A complete app: phonetic normalization × edit distance, dual-index dictionary, formally verified rules	phonetic_spellcheck/

---

All runnable examples

The full set of programs under examples/, grouped by theme. Run any of them with cargo run --example <name>; entries that need Cargo features list them in the Features column (omit the column when none are required). A handful are standalone Cargo packages or analysis harnesses rather than library demos — noted in their purpose.

crates.io note. Examples requiring pathmap-backend use a git dependency and must be built from source (they are unavailable from a plain crates.io install).

Getting started

Example	Purpose	Features
spell_checker.rs	Minimal fuzzy spell checker: dictionary + transducer, query and query_with_distance, Standard vs Transposition	—
builder_demo.rs	The TransducerBuilder API for fluent transducer construction	—
batch_operations.rs	Bulk insert / contains / remove operations on a DynamicDawg	—

Dictionaries & backends

Example	Purpose	Features
dynamic_dictionary.rs	Runtime insert/remove on a DynamicDawg with a live, shared transducer (incl. concurrent reads)	—
dynamic_dawg_demo.rs	Online modifications of a DynamicDawg (byte alphabet)	—
dynamic_dawg_unicode.rs	DynamicDawgChar with full Unicode (char) support	—
suffix_automaton_demo.rs	Substring matching with a SuffixAutomaton	—
substring_search.rs	Comprehensive approximate substring search over suffix automata	—
test_backend_comparison.rs	Side-by-side contains behavior across dictionary backends	—
custom_sync_strategy.rs	A custom backend declaring its own SyncStrategy for the transducer	pathmap-backend

Queries, algorithms & substitutions

Example	Purpose	Features
ordered_query_demo.rs	query_ordered: distance-first, lexicographic results; lazy top-$k$ and distance-bounded queries	—
ordered_query_benchmark.rs	Micro-benchmark: ordered vs unordered query iterators	—
unicode_diacritics.rs	SubstitutionSetChar presets (Latin diacritics, Greek/Cyrillic case-fold, kana) + custom sets	—
custom_substitutions.rs	Build and combine byte-level SubstitutionSets for domain-specific matching	—
phonetic_matching.rs	Restricted substitutions for sound-alike matching (no rules feature needed)	—
code_completion_demo.rs	Code completion via prefix matching and result filtering	—
position_skip_test.rs	Correctness check that automaton position-skipping preserves results	—
trace_za_query.rs	Manual, step-by-step trace of automaton states for a tiny query ("za")	—

Values, fuzzy maps & caching

Example	Purpose	Features
fuzzy_maps_code_completion.rs	Terms→scope-ID fuzzy map; filter, prioritize, and prune matches by value	pathmap-backend
fuzzy_cache_basic.rs	Wrapping a dictionary in a cache-eviction decorator	pathmap-backend
mork_fuzzy_query.rs	Zero-plumbing fuzzy queries over a bare, borrowed PathMap (MORK-style)	pathmap-backend

Contextual completion

Example	Purpose	Features
contextual_completion.rs	DynamicContextualCompletionEngine: drafts, checkpoints/undo, hierarchical scope visibility	pathmap-backend
hierarchical_scope_completion.rs	Lexical-scope completion built on fuzzy maps	pathmap-backend
advanced_contextual_filtering.rs	Bitmap-based node masking for fast contextual filtering	—
contextual_filtering_optimization.rs	Efficient contextual filtering via sub-trie construction	—

Phonetic matching

Example	Purpose	Features
phonetic_spellcheck/	Standalone project: PhoneticNormalizedDictionary over ~124k words (fuzzy, regex, pattern expansion)	phonetic-rules, pathmap-backend, embedded-rules
phonetic_fuzzy_matching.rs	Comprehensive phonetic rewrite × Levenshtein fuzzy matching	phonetic-rules
phonetic_rewrite.rs	Apply .llev phonetic rewrite rules to transform text	phonetic-rules
phonetic_iteration_analysis.rs	Measure iteration counts inside apply_rules_seq()	phonetic-rules
phonetic_slice_analysis.rs	Profile slice-copying overhead in phonetic rewriting	—

Performance & profiling

Example	Purpose	Features
real_world_benchmark.rs	Benchmark backends on a real English dictionary: build, contains, fuzzy query	—
profile.rs	Representative workload for flame-graph profiling / regression hunting	—
profile_workload.rs	Mixed-operation workload for flamegraph capture	—
scientific_eval.rs	Instrumented evaluation harness (custom allocator + PriorityQueryIterator) for metrics	—
simd_prototype.rs	Prototype illustrating the SIMD acceleration concepts	—
parallel_workspace_indexing.rs	Parallel per-document dictionary construction with binary-tree reduction	—
msm_experiment.rs	Deterministic Move–Split–Merge (time-series) optimization harness	—

Serialization

Example	Purpose	Features
serialization.rs	Save/load a DoubleArrayTrie via compact bincode and verify fuzzy queries round-trip	serialization
operation_set_persistence.rs	Round-trip a complete generalized edit grammar through bincode and protobuf	protobuf

---

← Documentation Index