harper-core 3.2.0

The language checker for developers.
Documentation
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
    }
}