module

Nucleoc

TODO: Write documentation for Nucleoc

Constants

BONUS_BOUNDARY = SCORE_MATCH // 2

BONUS_CAMEL123 = BONUS_BOUNDARY - PENALTY_GAP_START

BONUS_CONSECUTIVE = PENALTY_GAP_START + PENALTY_GAP_EXTENSION

BONUS_FIRST_CHAR_MULTIPLIER = 2_u16

BONUS_NON_WORD = BONUS_BOUNDARY

MAX_PREFIX_BONUS = BONUS_BOUNDARY

PARALLEL_ENABLED = (ENV["NUCLEOC_PARALLEL"]? != "false") && System.cpu_count > 1

Parallel processing enabled flag Crystal 1.x requires -Dpreview_mt for true multithreading across CPU cores Without it, fibers run on single OS thread (parallel overhead but no benefit) We'll use a pragmatic approach: enable parallel when we have multiple CPUs Users can force disable with NUCLEOC_PARALLEL=false

PENALTY_GAP_EXTENSION = 1_u16

PENALTY_GAP_START = 3_u16

PREFIX_BONUS_SCALE = 2_u16

SCORE_MATCH = 16_u16

Score constants

UNMATCHED = ScoreCell.new(0_u16, 0_u8, true)

Unmatched score cell constant

VERSION = "0.1.0"

Class methods

fuzzy_match(haystack : String, needle : String, config : Config = Config.new) : UInt16 | Nil

fuzzy_match_indices(haystack : String, needle : String, config : Config = Config.new) : Tuple(UInt16, Array(UInt32)) | Nil

has_ascii_graphemes(string : String) : Bool

match_list(items : Array(String), pattern : String, config : Config = Config.new, max_results : Int32 | Nil = nil) : Array(MatchResult)

Simple match_list implementation for compatibility with tests

new_matcher(config : Config = Config.new, max_results : Int32 | Nil = nil) : Nucleoc::Nucleo(String)

new_matcher(type : T.class, config : Config = Config.new, max_results : Int32 | Nil = nil) : Nucleoc::Nucleo(T) forall T

next_m_cell(p_score : UInt16, bonus : UInt16, m_cell : ScoreCell) : ScoreCell

Calculate the score for a match

p_score(prev_p_score : UInt16, prev_m_score : UInt16) : Tuple(UInt16, Bool)

Calculate the p_score (gap penalty)

parallel_fuzzy_indices(haystacks : Array(String), needle : String, config : Config = Config.new, workers : Int32 | Nil = nil, strategy : Symbol = :auto) : Array(Tuple(UInt16, Array(UInt32)) | Nil)

Parallel fuzzy match with indices across many haystacks using a shared needle. Returns an array of optional tuples {score, indices} in the same order as the input. Uses worker pools for proper concurrent processing.

parallel_fuzzy_match(haystacks : Array(String), needle : String, config : Config = Config.new, workers : Int32 | Nil = nil, strategy : Symbol = :auto) : Array(UInt16 | Nil)

Parallel fuzzy match across many haystacks using a shared needle. Returns an array of optional scores in the same order as the input. Uses worker pools for proper concurrent processing.

parallel_match_list(items : Array(String), pattern : String, config : Config = Config.new, max_results : Int32 | Nil = nil, workers : Int32 | Nil = nil, strategy : Symbol = :auto) : Array(MatchResult)

Parallel match_list implementation with top-k optimization

parallel_top_k_match(items : Array(String), pattern : String, k : Int32, config : Config = Config.new, workers : Int32 | Nil = nil) : Array(MatchResult)

Optimized parallel match with top-k selection Each worker keeps top-k results, reducing data transfer and sorting

postfix_match(haystack : String, needle : String, config : Config = Config.new) : UInt16 | Nil

prefix_match(haystack : String, needle : String, config : Config = Config.new) : UInt16 | Nil

substring_match(haystack : String, needle : String, config : Config = Config.new) : UInt16 | Nil