Offline, privacy-first grammar checker. Fast, open-source, Rust-powered
use std::{
ops::Index,
sync::{Arc, LazyLock},
};
use hashbrown::{DefaultHashBuilder, HashMap};
use indexmap::IndexMap;
use crate::{
DictWordMetadata,
spell::{
dictionary::{ANNOTATIONS_STR, CURATED_DICT_STR},
rune::{self, AttributeList, parse_word_list},
word_id::{CanonicalWordId, CaseFoldedWordId},
},
};
pub mod word_map_entry;
pub use word_map_entry::WordMapEntry;
/// Type used to store the canonical entries in the word map.
///
/// This currently uses an [`IndexMap`], so a word can be indexed either by its canonical word ID
/// (which is the same across all word maps), or directly via a `usize` index (specific to this
/// word map only).
///
/// The latter property is used to allow [`WordMap::case_folded`] to indirectly reference entries
/// in [`WordMap::canonical`].
type CanonicalStorage = IndexMap<CanonicalWordId, WordMapEntry, DefaultHashBuilder>;
/// The most basic dictionary. Stores a list of words and their metadata, while allowing for
/// efficient case-folded lookups.
///
/// This is the underlying data structure for all other dictionaries (at the time of writing).
#[derive(Debug, Clone, Eq, PartialEq, Default)]
pub struct WordMap {
/// Underlying container for the entries in the word map.
canonical: CanonicalStorage,
/// A map containing indices into `canonical` for a specific `CaseFoldedWordId`. This is used for
/// case-folded lookups in the word map.
case_folded: HashMap<CaseFoldedWordId, Vec<usize>>,
}
impl WordMap {
/// Create an empty word map.
pub fn new() -> Self {
Default::default()
}
/// A word map containing entries from the curated dictionary.
pub fn curated() -> Arc<Self> {
/// A word map containing entries from the curated dictionary.
static CURATED: LazyLock<Arc<WordMap>> = LazyLock::new(|| {
Arc::new(WordMap::from_rune_files(CURATED_DICT_STR, ANNOTATIONS_STR).unwrap())
});
(*CURATED).clone()
}
/// Does the word map contain a word with the given [`CanonicalWordId`]?
pub fn contains_canonical(&self, id: CanonicalWordId) -> bool {
self.get_canonical(id).is_some()
}
/// Does the word map contain any words with the given [`CaseFoldedWordId`]?
pub fn contains_case_folded(&self, id: CaseFoldedWordId) -> bool {
!self.get_canonical_indices_from_case_folded(id).is_empty()
}
/// Get an entry from the word map using a word identifier.
pub fn get_canonical(&self, id: CanonicalWordId) -> Option<&WordMapEntry> {
self.canonical.get(&id)
}
/// Get the entries corresponding to the provided [`CaseFoldedWordId`].
pub fn get_case_folded(
&self,
id: CaseFoldedWordId,
) -> impl ExactSizeIterator<Item = &WordMapEntry> {
self.get_canonical_indices_from_case_folded(id)
.iter()
.map(|canonical_index| &self[*canonical_index])
}
/// Convenience wrapper for [`Self::get_case_folded`].
///
/// This recalculates the word ID every time. If you're going to be querying the same word
/// multiple times, consider storing the word ID and using [`Self::get_case_folded`] instead.
pub fn get_case_folded_chars(
&self,
word: &[char],
) -> impl ExactSizeIterator<Item = &WordMapEntry> + use<'_> {
self.get_case_folded(CaseFoldedWordId::from_word_chars(word).0)
}
/// Borrow a word's metadata mutably
pub fn get_metadata_mut_canonical(
&mut self,
id: CanonicalWordId,
) -> Option<&mut DictWordMetadata> {
self.canonical.get_mut(&id).map(|v| &mut v.metadata)
}
/// Insert an entry into the word map.
///
/// This will merge the new metadata with the existing if an entry with an identical
/// [`CanonicalWordId`] is already contained in the word map.
///
/// If you are appending many words, consider using [`Self::extend`] instead.
pub fn insert(&mut self, entry: WordMapEntry) {
let (canonical_id, case_folded_id) =
(entry.word_ids.canonical(), entry.word_ids.case_folded());
if let Some(existing_entry) = self.canonical.get_mut(&canonical_id) {
// An existing word with the same canonical ID exists; update its entry.
existing_entry.metadata.merge(&entry.metadata);
} else {
// An existing word with the same canonical ID does NOT exist; insert it.
let (canonical_idx, _) = self.canonical.insert_full(canonical_id, entry);
if let Some(existing_case_folded_entry) = self.case_folded.get_mut(&case_folded_id) {
// `case_folded` already has a canonical ID list for this word; append to it, if
// the same entry does not already exist.
if !existing_case_folded_entry.contains(&canonical_idx) {
existing_case_folded_entry.push(canonical_idx);
}
} else {
// `case_folded` does NOT have a canonical ID list for this word; initialize one.
self.case_folded.insert(case_folded_id, vec![canonical_idx]);
}
}
}
/// Reserves capacity for at least `additional` more elements to be inserted
/// in the `WordMap`. The collection may reserve more space to avoid
/// frequent reallocations.
pub fn reserve(&mut self, additional: usize) {
self.canonical.reserve(additional);
}
/// Iterate through the canonical spellings of the words in the map.
pub fn iter(&self) -> impl ExactSizeIterator<Item = &WordMapEntry> {
self.canonical.values()
}
/// The number of words in the word map.
pub fn len(&self) -> usize {
self.canonical.len()
}
pub fn is_empty(&self) -> bool {
self.len() == 0
}
pub fn with_capacity(capacity: usize) -> Self {
Self {
canonical: IndexMap::with_capacity_and_hasher(capacity, DefaultHashBuilder::default()),
case_folded: HashMap::new(),
}
}
pub fn from_rune_files(word_list: &str, attr_list: &str) -> Result<Self, rune::Error> {
let word_list = parse_word_list(word_list)?;
let attr_list = AttributeList::parse(attr_list)?;
let mut word_map = WordMap::default();
attr_list.expand_annotated_words(word_list, &mut word_map);
Ok(word_map)
}
/// Get indices into [`Self::canonical`] using the provided [`CaseFoldedWordId`].
fn get_canonical_indices_from_case_folded(&self, id: CaseFoldedWordId) -> &[usize] {
self.case_folded
.get(&id)
.map_or(&[], |canonical_indices| canonical_indices)
}
}
// Functions for backward compatibility.
impl WordMap {
/// Append a single word to the dictionary.
///
/// If you are appending many words, consider using [`Self::extend_words`]
/// instead.
pub fn append_word(&mut self, word: impl AsRef<[char]>, metadata: DictWordMetadata) {
self.insert(WordMapEntry::new(word.as_ref()).with_md(metadata));
}
/// Append a single word to the dictionary.
///
/// If you are appending many words, consider using [`Self::extend_words`]
/// instead.
pub fn append_word_str(&mut self, word: &str, metadata: DictWordMetadata) {
self.insert(WordMapEntry::new_str(word).with_md(metadata));
}
/// Appends words to the dictionary.
pub fn extend_words(
&mut self,
words: impl IntoIterator<Item = (impl AsRef<[char]>, DictWordMetadata)>,
) {
self.extend(words.into_iter().map(|(canonical_spelling, metadata)| {
WordMapEntry::new(canonical_spelling.as_ref()).with_md(metadata)
}))
}
}
impl Extend<WordMapEntry> for WordMap {
fn extend<T: IntoIterator<Item = WordMapEntry>>(&mut self, iter: T) {
// [Copied from HashBrown::map::HashMap::extend]
// Keys may be already present or show multiple times in the iterator.
// Reserve the entire hint lower bound if the map is empty.
// Otherwise reserve half the hint (rounded up), so the map
// will only resize twice in the worst case.
let iter = iter.into_iter();
let reserve = if self.is_empty() {
iter.size_hint().0
} else {
iter.size_hint().0.div_ceil(2)
};
self.reserve(reserve);
iter.for_each(move |wme| {
self.insert(wme);
});
}
}
impl Index<usize> for WordMap {
type Output = <CanonicalStorage as Index<usize>>::Output;
fn index(&self, index: usize) -> &Self::Output {
&self.canonical[index]
}
}
impl IntoIterator for WordMap {
type Item = WordMapEntry;
type IntoIter = indexmap::map::IntoValues<CanonicalWordId, WordMapEntry>;
fn into_iter(self) -> Self::IntoIter {
self.canonical.into_values()
}
}
impl FromIterator<WordMapEntry> for WordMap {
fn from_iter<T: IntoIterator<Item = WordMapEntry>>(iter: T) -> Self {
let mut out = Self::new();
out.extend(iter);
out
}
}