Nucleo Matcher

https://docs.rs/nucleo-matcher/0.3.1/
Admin
Nucleo Matcher is a low-level Rust crate providing a highly optimized fuzzy matching implementation,...
Tokens:46,676
Snippets:361
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### normalize character example

Source: https://docs.rs/nucleo-matcher/0.3.1/nucleo_matcher/chars/fn.normalize.html

Example showing the normalization of a unicode character to its ASCII equivalent.

```rust
assert_eq!(normalize('ä'), 'a');
```

--------------------------------

### MatcherDataView Setup

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/fuzzy_optimal.rs.html

Sets up the `MatcherDataView` for fuzzy matching. It initializes the first row of the matrix based on the needle characters and calculates initial bonuses.

```rust
fn setup<const INDICES: bool, N: Char>(
        &mut self,
        needle: &[N],
        mut prev_class: CharClass,
        config: &Config,
        start: u32,
    ) -> bool
    where
        H: PartialEq<N>,
    {
        let mut row_iter = needle.iter().copied().zip(self.row_offs.iter_mut());
        let (mut needle_char, mut row_start) = row_iter.next().unwrap();

        let col_iter = self
            .haystack
            .iter_mut()
            .zip(self.bonus.iter_mut())
            .enumerate();

        let mut matched = false;
        for (i, (c_, bonus_)) in col_iter {
            let (c, class) = c_.char_class_and_normalize(config);
            *c_ = c;

            let bonus = config.bonus_for(prev_class, class);

```

--------------------------------

### Unicode Character Normalization Example

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/chars/normalize.rs.html

Demonstrates how to normalize a Unicode character by converting a Latin variant to its ASCII equivalent using the `normalize` function. This is useful for case-insensitive matching or simplifying text.

```rust
pub fn normalize(c: char) -> char {
    let i = c as u32;
    if i < DATA1_START || i >= DATA3_END {
        return c;
    }
    if i < DATA1_END {
        return TABLE1[(i - DATA1_START) as usize];
    }
    if i < DATA2_START {
        return c;
    }
    if i < DATA2_END {
        return TABLE2[(i - DATA2_START) as usize];
    }
    if i < DATA3_START {
        return c;
    }
    TABLE3[(i - DATA3_START) as usize]
}
```

--------------------------------

### Deduplicate and sort match indices

Source: https://docs.rs/nucleo-matcher/0.3.1/nucleo_matcher/pattern/struct.Pattern.html

Example of how to process match indices obtained from the indices method to ensure they are unique and sorted for highlighting.

```rust
indices.sort_unstable();
indices.dedup();
```

--------------------------------

### Unicode Normalization Test Case

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/chars/normalize.rs.html

An example demonstrating the usage of the `normalize` function to convert a specific Unicode character ('ä') to its normalized ASCII form ('a'). This serves as a basic test case for the normalization logic.

```rust
# use nucleo_matcher::chars::normalize;

assert_eq!(normalize('ä'), 'a');

```

--------------------------------

### Unicode Substring Match

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Finds a single Unicode character needle within a Unicode haystack. Returns the start index.

```rust
if let &[needle] = needle {
                    let (start, _) = self.prefilter_non_ascii(haystack, needle_, true)?;
                    let res = self
                        .substring_match_1_non_ascii::<INDICES>(haystack, needle, start, indices);
                    return Some(res);
                }
```

--------------------------------

### Greedy Fuzzy Match Implementation (ASCII)

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Implements a greedy fuzzy match for ASCII haystacks and needles. It uses prefilters to find potential start and end points for the match.

```rust
pub fn fuzzy_indices_greedy(
        &mut self,
        haystack: Utf32Str<'_>,
        needle: Utf32Str<'_>,
        indices: &mut Vec<u32>,
    ) -> Option<u16> {
        assert!(haystack.len() <= u32::MAX as usize);
        self.fuzzy_match_greedy_impl::<true>(haystack, needle, indices)
    }
```

```rust
fn fuzzy_match_greedy_impl<const INDICES: bool>(
        &mut self,
        haystack: Utf32Str<'_>,
        needle_: Utf32Str<'_>,
        indices: &mut Vec<u32>,
    ) -> Option<u16> {
        if needle_.len() > haystack.len() {
            return None;
        }
        if needle_.is_empty() {
            return Some(0);
        }
        if needle_.len() == haystack.len() {
            return self.exact_match_impl::<INDICES>(haystack, needle_, 0, haystack.len(), indices);
        }
        assert!(
            haystack.len() <= u32::MAX as usize,
            "matching is only support for up to 2^32-1 codepoints"
        );
        match (haystack, needle_) {
            (Utf32Str::Ascii(haystack), Utf32Str::Ascii(needle)) => {
                let (start, greedy_end, _) = self.prefilter_ascii(haystack, needle, true)?;
                if needle_.len() == greedy_end - start {
                    return Some(self.calculate_score::<INDICES, _, _>(
                        AsciiChar::cast(haystack),
                        AsciiChar::cast(needle),
                        start,
                        greedy_end,
                        indices,
                    ));
                }
                self.fuzzy_match_greedy_::<INDICES, AsciiChar, AsciiChar>(
                    AsciiChar::cast(haystack),
                    AsciiChar::cast(needle),
                    start,
                    greedy_end,
                    indices,
                )
            }
            (Utf32Str::Ascii(_), Utf32Str::Unicode(_)) => {
                // a purely ascii haystack can never be transformed to match
                // a needle that contains non-ascii chars since we don't allow gaps
                None
            }
            (Utf32Str::Unicode(haystack), Utf32Str::Ascii(needle)) => {
                let (start, _) = self.prefilter_non_ascii(haystack, needle_, true)?;
                self.fuzzy_match_greedy_::<INDICES, char, AsciiChar>(
                    haystack,
                    AsciiChar::cast(needle),
                    start,
                    start + 1,
                    indices,
                )
            }
            (Utf32Str::Unicode(haystack), Utf32Str::Unicode(needle)) => {
                let (start, _) = self.prefilter_non_ascii(haystack, needle_, true)?;
                self.fuzzy_match_greedy_::<INDICES, char, char>(
                    haystack,
                    needle,
                    start,
                    start + 1,
                    indices,
                )
            }
        }
    }
```

--------------------------------

### Optimal Fuzzy Matching Function

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/fuzzy_optimal.rs.html

Implements the core fuzzy optimal matching logic using a dynamic programming matrix. It handles allocation, setup, population, and reconstruction of the optimal path. Returns `None` if the input is too large or if no match is found.

```rust
pub(crate) fn fuzzy_match_optimal<const INDICES: bool, H: Char + PartialEq<N>, N: Char>(
        &mut self,
        haystack: &[H],
        needle: &[N],
        start: usize,
        greedy_end: usize,
        end: usize,
        indices: &mut Vec<u32>,
    ) -> Option<u16> {
        // construct a matrix (and copy the haystack), the matrix and haystack size are bounded
        // to avoid the slow O(mn) time complexity for large inputs. Furthermore, it allows
        // us to treat needle indices as u16
        let Some(mut matrix) = self.slab.alloc(&haystack[start..end], needle.len()) else {
            return self.fuzzy_match_greedy_::<INDICES, H, N>(
                haystack, needle, start, greedy_end, indices,
            );
        };

        let prev_class = start
            .checked_sub(1)
            .map(|i| haystack[i].char_class(&self.config))
            .unwrap_or(self.config.initial_char_class);
        let matched = matrix.setup::<INDICES, _>(needle, prev_class, &self.config, start as u32);
        // this only happened with unicode haystacks, for ASCII the prefilter handles all rejects
        if !matched {
            assert!(
                !N::ASCII || !H::ASCII,
                "should have been caught by prefilter"
            );
            return None;
        }

        // populate the matrix and find the best score
        let matrix_len = matrix.populate_matrix::<INDICES, _>(needle);
        let last_row_off = matrix.row_offs[needle.len() - 1];
        let relative_last_row_off = last_row_off as usize + 1 - needle.len();
        let (match_end, match_score_cell) = matrix.current_row[relative_last_row_off..]
            .iter()
            .enumerate()
            .max_by_key(|(_, cell)| cell.score)
            .expect("there must be atleast one match");
        if INDICES {
            matrix.reconstruct_optimal_path(match_end as u16, indices, matrix_len, start as u32);
        }
        Some(match_score_cell.score)
    }
```

--------------------------------

### Exact Match Implementation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Handles exact matching for a given needle within a haystack, returning the start and end indices. This is used when the needle and haystack lengths are equal.

```rust
if needle_.len() == haystack_.len() {
            return self.exact_match_impl::<INDICES>(
                haystack_,
                needle_,
                0,
                haystack_.len(),
                indices,
            );
        }
```

--------------------------------

### Substring Match with Prefilter for ASCII

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/exact.rs.html

Performs an ASCII substring match using a prefilter to quickly narrow down potential starting positions. It compares the substring after the prefilter length with the remaining part of the needle, considering character class bonuses.

```Rust
pub(crate) fn substring_match_ascii_with_prefilter(
        &mut self,
        haystack: &[u8],
        needle: &[u8],
        prefilter_len: usize,
        prefilter: impl Iterator<Item = usize>,
    ) -> (u16, usize) {
        let needle_without_prefilter = &needle[prefilter_len..];
        let mut max_score = 0;
        let mut max_pos = 0;
        for i in prefilter {
            let prev_char_class = i
                .checked_sub(1)
                .map(|i| AsciiChar(haystack[i]).char_class(&self.config))
                .unwrap_or(self.config.initial_char_class);
            let char_class = AsciiChar(haystack[i]).char_class(&self.config);
            let bonus = self.config.bonus_for(prev_char_class, char_class);
            let score = bonus * BONUS_FIRST_CHAR_MULTIPLIER + SCORE_MATCH;
            if score > max_score
                && haystack[i + prefilter_len..(i + needle.len()).min(haystack.len())]
                    .iter()
                    .map(|&c| AsciiChar(c).normalize(&self.config).0)
                    .eq(needle_without_prefilter.iter().copied())
            {
                max_pos = i;
                max_score = score;
                // can't get better than this
                if bonus >= self.config.bonus_boundary_white {
                    break;
                }
            }
        }
        (max_score, max_pos)
    }
```

--------------------------------

### Get First Character from Utf32Str

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Retrieves the first character from a Utf32Str. This is a utility function for internal use.

```rust
pub(crate) fn first(self) -> char {
        match self {
            Utf32Str::Ascii(bytes) => bytes[0] as char,
            Utf32Str::Unicode(codepoints) => codepoints[0],
        }
    }
```

--------------------------------

### Create a New Matcher Instance

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Instantiates a new `Matcher` with a given configuration. Note that this allocates significant heap memory, so reusing matchers is recommended for frequent use.

```rust
pub fn new(config: Config) -> Self {
    Self {
        config,
        slab: MatrixSlab::new(),
    }
}
```

--------------------------------

### Get Last Character from Utf32Str

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Retrieves the last character from a Utf32Str. This is a utility function for internal use.

```rust
pub(crate) fn last(self) -> char {
        match self {
            Utf32Str::Ascii(bytes) => bytes[bytes.len() - 1] as char,
            Utf32Str::Unicode(codepoints) => codepoints[codepoints.len() - 1],
        }
    }
```

--------------------------------

### Configure Matcher for File Paths (Immutable)

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

Returns a new `Config` instance configured for matching file paths. Adjusts delimiter characters and boundary bonuses, with OS-specific handling for Windows.

```rust
    pub const fn match_paths(mut self) -> Self {
        if cfg!(windows) {
            self.delimiter_chars = b"/\\";
        } else {
            self.delimiter_chars = b"/";
        }
        self.bonus_boundary_white = BONUS_BOUNDARY;
        self.initial_char_class = CharClass::Delimiter;
        self
    }
```

--------------------------------

### Get nth Character from Utf32Str

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Retrieves the character at a specific index (u32) from a Utf32Str. Handles both ASCII and Unicode representations.

```rust
pub fn get(self, n: u32) -> char {
        match self {
            Utf32Str::Ascii(bytes) => bytes[n as usize] as char,
            Utf32Str::Unicode(codepoints) => codepoints[n as usize],
        }
    }
```

--------------------------------

### Getting the Length of Utf32Str

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Returns the number of characters (codepoints) in the `Utf32Str`. This method works efficiently for both ASCII and Unicode variants.

```rust
pub fn len(self) -> usize {
    match self {
        Utf32Str::Unicode(codepoints) => codepoints.len(),
        Utf32Str::Ascii(ascii_bytes) => ascii_bytes.len(),
    }
}
```

--------------------------------

### Atom Constructor with Options

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/pattern.rs.html

Creates a new `Atom` instance, allowing configuration of case sensitivity, Unicode normalization, matching kind, and whitespace escaping.

```Rust
pub fn new(
        needle: &str,
        case: CaseMatching,
        normalize: Normalization,
        kind: AtomKind,
        escape_whitespace: bool,
    ) -> Atom {
        Atom::new_inner(needle, case, normalize, kind, escape_whitespace, false)
    }
```

--------------------------------

### Config::match_paths

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

Returns a new Config instance configured with bonuses appropriate for matching file paths. This is a const function.

```APIDOC
## Method Config::match_paths

### Description
Configures the matcher with bonuses appropriate for matching file paths. This is a const function that returns a modified `Config` instance.

### Behavior
- If running on Windows, `delimiter_chars` is set to `b"/\\".`
- Otherwise, `delimiter_chars` is set to `b"/".`
- `bonus_boundary_white` is set to `BONUS_BOUNDARY`.
- `initial_char_class` is set to `CharClass::Delimiter`.
```

--------------------------------

### Unicode Substring Match with ASCII Needle

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Finds a single ASCII character needle within a Unicode haystack. Returns the start index.

```rust
if let &[needle] = needle {
                    let (start, _) = self.prefilter_non_ascii(haystack, needle_, true)?;
                    let res = self.substring_match_1_non_ascii::<INDICES>(
                        haystack,
                        needle as char,
                        start,
                        indices,
                    );
                    return Some(res);
                }
```

--------------------------------

### Matcher::new

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Creates a new matcher instance. This method eagerly allocates a significant amount of heap memory, so it's recommended to reuse matcher instances if they are called frequently, such as within a loop.

```APIDOC
## Matcher::new

### Description
Creates a new matcher instance. Note that this will eagerly allocate a fairly large chunk of heap memory (around 135KB currently but subject to change), so matchers should be reused if called often (like in a loop).

### Method
`Matcher::new(config: Config) -> Self`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let config = Config::DEFAULT;
let matcher = Matcher::new(config);
```

### Response
#### Success Response
A new `Matcher` instance.

#### Response Example
```rust
// Returns a Matcher instance
```
```

--------------------------------

### Unicode Data Table Generation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/chars/normalize.rs.html

Illustrates the process of generating a lookup table for Unicode character normalization. It defines sparse data and uses a generic function to create a dense table for efficient character mapping.

```rust
const fn generate_table<const LEN: usize>(sparse_data: &[(char, char)]) -> [char; LEN] {
    let mut table: [char; LEN] = ['\0'; LEN];
    let start = sparse_data[0].0 as u32;
    let mut i = 0u32;
    let mut j = 0;
    while i < table.len() as u32 {
        let key = unsafe { transmute(start + i) };
        if sparse_data[j].0 == key {
            table[i as usize] = DATA1[j].1;
            j += 1;
        } else {
            //identity
            table[i as usize] = key;
        }
        i += 1;
    }
    table
}
```

--------------------------------

### Calculate Previous Score

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/fuzzy_optimal.rs.html

Calculates the previous score, determining whether a match or a skip operation was more beneficial. It applies penalties for gap extension or start.

```rust
fn p_score(prev_p_score: u16, prev_m_score: u16) -> (u16, bool) {
    let score_match = prev_m_score.saturating_sub(PENALTY_GAP_START);
    let score_skip = prev_p_score.saturating_sub(PENALTY_GAP_EXTENSION);
    if score_match > score_skip {
        (score_match, true)
    } else {
        (score_skip, false)
    }
}
```

--------------------------------

### Configure Matcher for File Paths (Mutable)

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

Mutably configures the matcher with settings appropriate for file paths. Adjusts delimiter characters and boundary bonuses based on the operating system (Windows vs. others).

```rust
    pub fn set_match_paths(&mut self) {
        if cfg!(windows) {
            self.delimiter_chars = b"/:\\";
        } else {
            self.delimiter_chars = b"/:";
        }
        self.bonus_boundary_white = BONUS_BOUNDARY;
        self.initial_char_class = CharClass::Delimiter;
    }
```

--------------------------------

### Default Config for nucleo_matcher

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

Provides the default configuration settings for the nucleo matcher. This is implemented as a constant due to `Default::default` not being callable in a const context.

```rust
1use crate::chars::CharClass;
2use crate::score::BONUS_BOUNDARY;
3
4/// Configuration data that controls how a matcher behaves
5#[non_exhaustive]
6#[derive(PartialEq, Eq, Debug, Clone)]
7pub struct Config {
8    /// Characters that act as delimiters and provide bonus
9    /// for matching the following char
10    pub(crate) delimiter_chars: &'static [u8],
11    /// Extra bonus for word boundary after whitespace character or beginning of the string
12    pub(crate) bonus_boundary_white: u16,
13    /// Extra bonus for word boundary after slash, colon, semi-colon, and comma
14    pub(crate) bonus_boundary_delimiter: u16,
15    pub(crate) initial_char_class: CharClass,
16
17    /// Whether to normalize latin script characters to ASCII (enabled by default)
18    pub normalize: bool,
19    /// whether to ignore casing
20    pub ignore_case: bool,
21    /// Whether to provide a bonus to matches by their distance from the start
22    /// of the haystack. The bonus is fairly small compared to the normal gap
23    /// penalty to avoid messing with the normal score heuristic. This setting
24    /// is not turned on by default and only recommended for autocompletion
25    /// usecases where the expectation is that the user is typing the entire
26    /// match. For a full fzf-like fuzzy matcher/picker word segmentation and
27    /// explicit prefix literals should be used instead.
28    pub prefer_prefix: bool,
29}
30
31impl Config {
32    /// The default config for nucleo, implemented as a constant since
33    /// Default::default can not be called in a const context
34    pub const DEFAULT: Self = {
35        Config {
36            delimiter_chars: b"/,:;|",
37            bonus_boundary_white: BONUS_BOUNDARY + 2,
38            bonus_boundary_delimiter: BONUS_BOUNDARY + 1,
39            initial_char_class: CharClass::Whitespace,
40            normalize: true,
41            ignore_case: true,
42            prefer_prefix: false,
43        }
44    };
45}
```

--------------------------------

### MatrixCell Structure and Methods

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/matrix.rs.html

Represents a single cell in the matching matrix, storing information about partial and main matches. It provides methods to set and get match states efficiently.

```rust
#[repr(transparent)]
pub struct MatrixCell(pub(crate) u8);

impl MatrixCell {
    pub fn set(&mut self, p_match: bool, m_match: bool) {
        self.0 = p_match as u8 | ((m_match as u8) << 1);
    }

    pub fn get(&self, m_matrix: bool) -> bool {
        let mask = m_matrix as u8 + 1;
        (self.0 & mask) != 0
    }
}
```

--------------------------------

### Config::set_match_paths

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

Configures the matcher with bonuses appropriate for matching file paths. This method modifies the existing Config instance.

```APIDOC
## Method Config::set_match_paths

### Description
Configures the matcher with bonuses appropriate for matching file paths. This method mutates the `Config` instance.

### Behavior
- If running on Windows, `delimiter_chars` is set to `b"/:\\".`
- Otherwise, `delimiter_chars` is set to `b"/:".`
- `bonus_boundary_white` is set to `BONUS_BOUNDARY`.
- `initial_char_class` is set to `CharClass::Delimiter`.
```

--------------------------------

### Match items using Pattern::parse

Source: https://docs.rs/nucleo-matcher/0.3.1/nucleo_matcher/index.html

Demonstrates using the Pattern::parse API to construct atoms for fuzzy matching against a list of paths.

```rust
let paths = ["foo/bar", "bar/foo", "foobar"];
let mut matcher = Matcher::new(Config::DEFAULT.match_paths());
let matches = Pattern::parse("foo bar", CaseMatching::Ignore, Normalization::Smart).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo/bar", 168), ("bar/foo", 168), ("foobar", 140)]);
let matches = Pattern::parse("^foo bar", CaseMatching::Ignore, Normalization::Smart).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo/bar", 168), ("foobar", 140)]);
```

--------------------------------

### Enum for Atom Matching Kinds

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/pattern.rs.html

Defines the different algorithms for matching a pattern atom against a haystack. Choose based on whether gaps are allowed, or if the match must be at the start, end, or exact.

```Rust
pub enum AtomKind {
    /// Fuzzy matching where the needle must match any haystack characters
    /// (match can contain gaps). This atom kind is used by default if no
    /// special syntax is used. There is no negated fuzzy matching (too
    /// many false positives).
    ///
    /// See also [`Matcher::fuzzy_match`](crate::Matcher::fuzzy_match).
    Fuzzy,
    /// The needle must match a contiguous sequence of haystack characters
    /// without gaps.  This atom kind is parsed from the following syntax:
    /// `'foo` and `!foo` (negated).
    ///
    /// See also [`Matcher::substring_match`](crate::Matcher::substring_match).
    Substring,
    /// The needle must match all leading haystack characters without gaps or
    /// prefix. This atom kind is parsed from the following syntax: `^foo` and
    /// `!^foo` (negated).
    ///
    /// See also [`Matcher::prefix_match`](crate::Matcher::prefix_match).
    Prefix,
    /// The needle must match all trailing haystack characters without gaps or
    /// postfix. This atom kind is parsed from the following syntax: `foo$` and
    /// `!foo$` (negated).
    ///
    /// See also [`Matcher::postfix_match`](crate::Matcher::postfix_match).
    Postfix,
    /// The needle must match all haystack characters without gaps or prefix.
    /// This atom kind is parsed from the following syntax: `^foo$` and `!^foo$`
    /// (negated).
    ///
    /// See also [`Matcher::exact_match`](crate::Matcher::exact_match).
    Exact,
}
```

--------------------------------

### Direct Atom Matching

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Illustrates creating a single `Atom` directly for matching when word segmentation is not desired. This is the most granular way to perform a match, useful for specific, non-word-based matching scenarios. The `false` argument indicates that the pattern is not a prefix.

```rust
# use nucleo_matcher::{Matcher, Config};
# use nucleo_matcher::pattern::{Pattern, Atom, CaseMatching, Normalization, AtomKind};
let paths = ["foobar", "foo bar"];
let mut matcher = Matcher::new(Config::DEFAULT);
let matches = Atom::new("foo bar", CaseMatching::Ignore, Normalization::Smart, AtomKind::Fuzzy, false).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo bar", 192)]);

```

--------------------------------

### Exact Match Functionality

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Performs an exact match between a haystack and a needle string. It handles leading and trailing whitespace based on the needle's characters and returns the starting index if a match is found.

```Rust
pub fn exact_match(&mut self, haystack: Utf32Str<'_>, needle: Utf32Str<'_>) -> Option<u16> {
        if needle.is_empty() {
            return Some(0);
        }
        let mut leading_space = 0;
        let mut trailing_space = 0;
        if !needle.first().is_whitespace() {
            leading_space = haystack.leading_white_space()
        }
        if !needle.last().is_whitespace() {
            trailing_space = haystack.trailing_white_space()
        }
        // avoid wraparound in size check
        if trailing_space == haystack.len() {
            return None;
        }
        self.exact_match_impl::<false>(
            haystack,
            needle,
            leading_space,
            haystack.len() - trailing_space,
            &mut Vec::new(),
        )
    }
```

--------------------------------

### Config::DEFAULT

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

Provides the default configuration for the Nucleo matcher. This is implemented as a constant because `Default::default()` cannot be called in a const context.

```APIDOC
## Associated Constant Config::DEFAULT

### Description
The default config for nucleo, implemented as a constant since `Default::default()` can not be called in a const context.

### Value
```rust
Config {
    delimiter_chars: b"/,:;|",
    bonus_boundary_white: BONUS_BOUNDARY + 2,
    bonus_boundary_delimiter: BONUS_BOUNDARY + 1,
    initial_char_class: CharClass::Whitespace,
    normalize: true,
    ignore_case: true,
    prefer_prefix: false,
}
```
```

--------------------------------

### Literal Matching with Pattern New

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Shows how to use `Pattern::new` for literal matching without automatic word segmentation. This is useful when the pattern should be matched exactly as provided, including spaces. The `AtomKind::Fuzzy` is specified for fuzzy matching behavior.

```rust
# use nucleo_matcher::{Matcher, Config};
# use nucleo_matcher::pattern::{Pattern, CaseMatching, AtomKind, Normalization};
let paths = ["foo/bar", "bar/foo", "foobar"];
let mut matcher = Matcher::new(Config::DEFAULT.match_paths());
let matches = Pattern::new("foo bar", CaseMatching::Ignore, Normalization::Smart, AtomKind::Fuzzy).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo/bar", 168), ("bar/foo", 168), ("foobar", 140)]);
let paths = ["^foo/bar", "bar/^foo", "foobar"];
let matches = Pattern::new("^foo bar", CaseMatching::Ignore, Normalization::Smart, AtomKind::Fuzzy).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("^foo/bar", 188), ("bar/^foo", 188)]);

```

--------------------------------

### Case-Insensitive ASCII Substring Match with Prefilter

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/exact.rs.html

Handles case-insensitive ASCII substring matching by utilizing a prefilter. If the needle starts with a lowercase letter, it searches for both the lowercase and uppercase versions of that character in the haystack to initiate the match.

```Rust
pub(crate) fn substring_match_ascii<const INDICES: bool>(
        &mut self,
        haystack: &[u8],
        needle: &[u8],
        indices: &mut Vec<u32>,
    ) -> Option<u16> {
        let mut max_score = 0;
        let mut max_pos = 0;
        if self.config.ignore_case {
            match needle.iter().position(|&c| c >= b'a' && c <= b'z') {
                // start with char do case insensitive search
                Some(0) => {
                    (max_score, max_pos) = self.substring_match_ascii_with_prefilter(
                        haystack,
                        needle,
                        1,
                        Memchr2::new(
                            needle[0],
                            needle[0] - 32,
                            &haystack[..haystack.len() - needle.len() + 1],
                        ),
                    );
                    if max_score == 0 {
                        return None;
                    }
                }
                _ => {
                    // TODO: implement case insensitive search for needle that does not start with lowercase
                }
            }
        } else {
            // TODO: implement case sensitive search
        }
        
        if max_score == 0 {
            return None;
        }

        if INDICES {
            indices.push(max_pos as u32);
        }
        Some(max_score)
    }
```

--------------------------------

### Match items using Atom::new

Source: https://docs.rs/nucleo-matcher/0.3.1/nucleo_matcher/index.html

Constructs a single Atom directly when word segmentation is not desired.

```rust
let paths = ["foobar", "foo bar"];
let mut matcher = Matcher::new(Config::DEFAULT);
let matches = Atom::new("foo bar", CaseMatching::Ignore, Normalization::Smart, AtomKind::Fuzzy, false).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo bar", 192)]);
```

--------------------------------

### Create a Pattern with Individual Word Matching

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/pattern.rs.html

Use `Pattern::new` to create a pattern where each word is matched individually. Whitespace can be escaped with '\'. No special parsing is done for characters like '$', '!', ''', or '^'.

```rust
pub fn new(
        pattern: &str,
        case_matching: CaseMatching,
        normalize: Normalization,
        kind: AtomKind,
    ) -> Pattern {
        let atoms = pattern_atoms(pattern)
            .filter_map(|pat| {
                let pat = Atom::new(pat, case_matching, normalize, kind, true);
                (!pat.needle.is_empty()).then_some(pat)
            })
            .collect();
        Pattern { atoms }
    }
```

--------------------------------

### Fuzzy Greedy Match Implementation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/fuzzy_greedy.rs.html

Implements a fast, linear-time fallback algorithm for fuzzy string matching. It prioritizes speed over the absolute best match quality, and its reported scores/indices might not always be optimal.

```rust
1use crate::chars::Char;
2use crate::Matcher;
3
4impl Matcher {
5    /// greedy fallback algorithm, much faster (linear time) but reported scores/indicies
6    /// might not be the best match
7    pub(crate) fn fuzzy_match_greedy_<const INDICES: bool, H: Char + PartialEq<N>, N: Char>(
8        &mut self,
9        haystack: &[H],
10        needle: &[N],
11        mut start: usize,
12        mut end: usize,
13        indices: &mut Vec<u32>,
14    ) -> Option<u16> {
15        let first_char_end = if H::ASCII && N::ASCII { start + 1 } else { end };
16        'nonascii: {
17            if !H::ASCII || !N::ASCII {
18                let mut needle_iter = needle[1..].iter().copied();
19                if let Some(mut needle_char) = needle_iter.next() {
20                    for (i, &c) in haystack[first_char_end..].iter().enumerate() {
21                        if c.normalize(&self.config) == needle_char {
22                            let Some(next_needle_char) = needle_iter.next() else {
23                                // we found a match so we are now in the same state
24                                // as the prefilter would produce
25                                end = first_char_end + i + 1;
26                                break 'nonascii;
27                            };
28                            needle_char = next_needle_char;
29                        }
30                    }
31                    // some needle chars were not matched bail out
32                    return None;
33                }
34            }
35        } // minimize the greedly match by greedy matching in reverse
36
37        let mut needle_iter = needle.iter().rev().copied();
38        let mut needle_char = needle_iter.next().unwrap();
39        for (i, &c) in haystack[start..end].iter().enumerate().rev() {
40            let c = c.normalize(&self.config);
41            if c == needle_char {
42                let Some(next_needle_char) = needle_iter.next() else {
43                    start += i;
44                    break;
45                };
46                needle_char = next_needle_char;
47            }
48        }
49        Some(self.calculate_score::<INDICES, H, N>(haystack, needle, start, end, indices))
50    }
51}

```

--------------------------------

### Reconstruct Optimal Match Path

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/fuzzy_optimal.rs.html

Reconstructs the optimal match path from the populated scoring matrix. This function backtracks from the maximum score to determine the sequence of matches. It requires the maximum score, a mutable vector to store indices, the matrix length, and a starting offset.

```Rust
fn reconstruct_optimal_path(
        &self,
        max_score_end: u16,
        indices: &mut Vec<u32>,
        matrix_len: usize,
        start: u32,
    ) {
        let indices_start = indices.len();
        indices.resize(indices_start + self.row_offs.len(), 0);
        let indices = &mut indices[indices_start..];
        let last_row_off = *self.row_offs.last().unwrap();
        indices[self.row_offs.len() - 1] = start + max_score_end as u32 + last_row_off as u32;

        let mut matrix_cells = &self.matrix_cells[..matrix_len];
        let width = self.current_row.len();
        let mut row_iter = self.row_offs[..self.row_offs.len() - 1]
            .iter()
            .copied()
            .enumerate()
            .rev()
            .map(|(i, off)| {
                let relative_off = off as usize - i;
                let row;
                (matrix_cells, row) = 
                    matrix_cells.split_at(matrix_cells.len() - (width - relative_off));
                (i, off, row)
            });
        let (mut row_idx, mut row_off, mut row) = row_iter.next().unwrap();
        let mut col = max_score_end;
        let relative_last_row_off = last_row_off as usize + 1 - self.row_offs.len();
        let mut matched = self.current_row[col as usize + relative_last_row_off].matched;
        col += last_row_off - row_off - 1;
        loop {
            if matched {
                indices[row_idx] = start + col as u32 + row_off as u32;
            }
            let next_matched = row[col as usize].get(matched);
            if matched {
                let Some((next_row_idx, next_row_off, next_row)) = row_iter.next() else {
                    break;
                };
                col += row_off - next_row_off;
                (row_idx, row_off, row) = (next_row_idx, next_row_off, next_row)
            }
            col -= 1;
            matched = next_matched;
        }
    }
```

--------------------------------

### Match and Sort a List of Items

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/pattern.rs.html

The `match_list` function provides a convenient way to match a list of items against the pattern and sort them by score. It is not recommended for large lists due to blocking the UI thread.

```rust
pub fn match_list<T: AsRef<str>>(
        &self,
        items: impl IntoIterator<Item = T>,
        matcher: &mut Matcher,
    ) -> Vec<(T, u32)> {
        if self.atoms.is_empty() {
            return items.into_iter().map(|item| (item, 0)).collect();
        }
        let mut buf = Vec::new();
        let mut items: Vec<_> = items
            .into_iter()
            .filter_map(|item| {
                self.score(Utf32Str::new(item.as_ref(), &mut buf), matcher)
                    .map(|score| (item, score))
            })
            .collect();
        items.sort_by_key(|(_, score)| Reverse(*score));
        items
    }
```

--------------------------------

### Fuzzy Matching with Pattern Parsing

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Demonstrates using the `Pattern::parse` API to match paths with space-separated words. This method automatically segments the pattern into atoms based on words. Use this when you want fuzzy matching with word segmentation.

```rust
# use nucleo_matcher::{Matcher, Config};
# use nucleo_matcher::pattern::{Pattern, Normalization, CaseMatching};
let paths = ["foo/bar", "bar/foo", "foobar"];
let mut matcher = Matcher::new(Config::DEFAULT.match_paths());
let matches = Pattern::parse("foo bar", CaseMatching::Ignore, Normalization::Smart).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo/bar", 168), ("bar/foo", 168), ("foobar", 140)]);
let matches = Pattern::parse("^foo bar", CaseMatching::Ignore, Normalization::Smart).match_list(paths, &mut matcher);
assert_eq!(matches, vec![("foo/bar", 168), ("foobar", 140)]);

```

--------------------------------

### Clone Pattern Implementation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/pattern.rs.html

Provides a basic clone implementation for the Pattern struct, copying its atoms.

```rust
impl Clone for Pattern {
    fn clone(&self) -> Self {
        Self {
            atoms: self.atoms.clone(),
        }
    }

    fn clone_from(&mut self, source: &Self) {
        self.atoms.clone_from(&source.atoms);
    }
}
```

--------------------------------

### MatrixSlab::new

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/matrix.rs.html

Creates a new MatrixSlab, allocating memory for MatcherData. Handles potential allocation errors.

```rust
pub fn new() -> Self {
        let layout = Layout::new::<MatcherData>();
        // safety: the matrix is never zero sized (hardcoded constants)
        let ptr = unsafe { alloc_zeroed(layout) };
        let Some(ptr) = NonNull::new(ptr) else {
            handle_alloc_error(layout)
        };
        MatrixSlab(ptr.cast())
    }
```

--------------------------------

### MatrixLayout Structure and Initialization

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/matrix.rs.html

Defines the memory layout for the matching matrix, calculating offsets for different data components based on haystack and needle lengths. It ensures that the total size does not exceed memory limits.

```rust
struct MatrixLayout<C: Char> {
    haystack_len: usize,
    needle_len: usize,
    layout: Layout,
    haystack_off: usize,
    bonus_off: usize,
    rows_off: usize,
    score_off: usize,
    matrix_off: usize,
    _phantom: PhantomData<C>,
}
impl<C: Char> MatrixLayout<C> {
    fn new(haystack_len: usize, needle_len: usize) -> MatrixLayout<C> {
        assert!(haystack_len >= needle_len);
        assert!(haystack_len <= u32::MAX as usize);
        let mut layout = Layout::from_size_align(0, 1).unwrap();
        let haystack_layout = Layout::array::<C>(haystack_len).unwrap();
        let bonus_layout = Layout::array::<u8>(haystack_len).unwrap();
        let rows_layout = Layout::array::<u16>(needle_len).unwrap();
        let score_layout = Layout::array::<ScoreCell>(haystack_len + 1 - needle_len).unwrap();
        let matrix_layout =
            Layout::array::<MatrixCell>((haystack_len + 1 - needle_len) * needle_len).unwrap();

        let haystack_off;
        (layout, haystack_off) = layout.extend(haystack_layout).unwrap();
        let bonus_off;
        (layout, bonus_off) = layout.extend(bonus_layout).unwrap();
        let rows_off;
        (layout, rows_off) = layout.extend(rows_layout).unwrap();
        let score_off;
        (layout, score_off) = layout.extend(score_layout).unwrap();
        let matrix_off;
        (layout, matrix_off) = layout.extend(matrix_layout).unwrap();
        MatrixLayout {
            haystack_len,
            needle_len,
            layout,
            haystack_off,
            bonus_off,
            rows_off,
            score_off,
            matrix_off,
            _phantom: PhantomData,
        }
    }
    // ... other methods
}
```

--------------------------------

### From<Cow<'a, str>> for Utf32String

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Converts a `Cow<'a, str>` (Clone-on-Write string) into a `Utf32String`, handling both borrowed and owned string data.

```APIDOC
## From<Cow<'a, str>> for Utf32String

### Description
Converts a `Cow<'a, str>` (Clone-on-Write string) into a `Utf32String`, handling both borrowed and owned string data.

### Method
Implementation of the `From<Cow<'a, str>>` trait for `Utf32String`.

### Parameters
- **value** (`Cow<'a, str>`): The `Cow` string to convert.

### Response
- Returns a `Utf32String` instance.
```

--------------------------------

### AsciiChar PartialEq<char> Implementation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/chars.rs.html

Implements PartialEq<AsciiChar> for char, allowing direct comparison between char and AsciiChar.

```rust
impl PartialEq<AsciiChar> for char {
    fn eq(&self, other: &AsciiChar) -> bool {
        other.0 as char == *self
    }
}
```

--------------------------------

### Unicode Prefilter and Fuzzy Match with ASCII Needle

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Applies a prefilter for Unicode haystacks and ASCII needles, then performs an optimal fuzzy match.

```rust
self.fuzzy_match_optimal::<INDICES, char, AsciiChar>(
                    haystack,
                    AsciiChar::cast(needle),
                    start,
                    start + 1,
                    end,
                    indices,
                )
```

--------------------------------

### From<String> for Utf32String

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Converts an owned `String` into a `Utf32String` by first converting it into a `Box<str>`.

```APIDOC
## From<String> for Utf32String

### Description
Converts an owned `String` into a `Utf32String` by first converting it into a `Box<str>`.

### Method
Implementation of the `From<String>` trait for `Utf32String`.

### Parameters
- **value** (`String`): The `String` to convert.

### Response
- Returns a `Utf32String` instance.
```

--------------------------------

### Config Struct

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/config.rs.html

The Config struct holds various settings that control how the Nucleo matcher operates. These include character delimiters, boundary bonuses, and options for normalization, case insensitivity, and prefix preference.

```APIDOC
## Struct Config

### Description
Configuration data that controls how a matcher behaves. This struct is non-exhaustive, allowing for future extensions without breaking changes.

### Fields
- **delimiter_chars** (`&'static [u8]`) - Characters that act as delimiters and provide bonus for matching the following char.
- **bonus_boundary_white** (`u16`) - Extra bonus for word boundary after whitespace character or beginning of the string.
- **bonus_boundary_delimiter** (`u16`) - Extra bonus for word boundary after slash, colon, semi-colon, and comma.
- **initial_char_class** (`CharClass`) - The initial character class for matching.
- **normalize** (`bool`) - Whether to normalize latin script characters to ASCII (enabled by default).
- **ignore_case** (`bool`) - Whether to ignore casing during matching.
- **prefer_prefix** (`bool`) - Whether to provide a bonus to matches by their distance from the start of the haystack. Recommended for autocompletion usecases.
```

--------------------------------

### Display Formatting for Utf32Str

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Implements the `Display` trait for Utf32Str, allowing it to be formatted as a regular string.

```rust
impl fmt::Display for Utf32Str<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for c in self.chars() {
            write!(f, "{c}")?
        }
        Ok(())
    }
}
```

--------------------------------

### Config Bonus Calculation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/score.rs.html

Calculates a bonus score based on the transition between previous and current character classes. This is used to prioritize matches at word boundaries or specific character types.

```rust
impl Config {
    #[inline]
    pub(crate) fn bonus_for(&self, prev_class: CharClass, class: CharClass) -> u16 {
        if class > CharClass::Delimiter {
            // transition from non word to word
            match prev_class {
                CharClass::Whitespace => return self.bonus_boundary_white,
                CharClass::Delimiter => return self.bonus_boundary_delimiter,
                CharClass::NonWord => return BONUS_BOUNDARY,
                _ => ()
            }
        }
        if prev_class == CharClass::Lower && class == CharClass::Upper
            || prev_class != CharClass::Number && class == CharClass::Number
        {
            // camelCase letter123
            BONUS_CAMEL123
        } else if class == CharClass::Whitespace {
            self.bonus_boundary_white
        } else if class == CharClass::NonWord {
            return BONUS_NON_WORD;
        } else {
            0
        }
    }
}
```

--------------------------------

### Display Implementation for Utf32String

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/utf32_str.rs.html

Provides a display representation for Utf32String by formatting its full slice.

```rust
impl fmt::Display for Utf32String {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.slice(..))
    }
}
```

--------------------------------

### Exact Match Implementation

Source: https://docs.rs/nucleo-matcher/0.3.1/src/nucleo_matcher/lib.rs.html

Internal implementation for exact matching, supporting optional index collection. Asserts that haystack length is within u32::MAX for matching.

```rust
fn exact_match_impl<const INDICES: bool>(
        &mut self,
        haystack: Utf32Str<'_>,
        needle_: Utf32Str<'_>,
        start: usize,
        end: usize,
        indices: &mut Vec<u32>,
    ) -> Option<u16> {
        if needle_.len() != end - start {
            return None;
        }
        assert!(
            haystack.len() <= u32::MAX as usize,
            "matching is only support for up to 2^32-1 codepoints"
        );
        let score = match (haystack, needle_) {
            (Utf32Str::Ascii(haystack), Utf32Str::Ascii(needle)) => {
                let matched = if self.config.ignore_case {
                    AsciiChar::cast(haystack)[start..end]
                        .iter()
                        .map(|c| c.normalize(&self.config))
                        .eq(AsciiChar::cast(needle)
                            .iter()
                            .map(|c| c.normalize(&self.config)))
                } else {
                    haystack == needle
                };
                if !matched {

```
Tokens:
Raw