ahocorasick_rs

When patterns overlap, you can control which match is returned using the matchkind argument in the constructor. This is supported by both AhoCorasick and BytesAhoCorasick.

Available MatchKind options:

• MatchKind.Standard (Default): Returns the pattern that matches first semantically (the one that ends earliest in the haystack).
• MatchKind.LeftmostFirst: Returns the leftmost-in-the-haystack pattern that appears first in the provided list of patterns.
• MatchKind.LeftmostLongest: Returns the leftmost-in-the-haystack pattern that is the longest.

To get all overlapping matches, use MatchKind.Standard and set overlapping=True in the search method.

from ahocorasick_rs import AhoCorasick, MatchKind

# LeftmostFirst example
ac = AhoCorasick(["disco", "disc"], matchkind=MatchKind.LeftmostFirst)
print(ac.find_matches_as_strings("discontent")) # ['disco']

# Overlapping matches example
patterns = ["winter", "onte", "disco", "discontent"]
ac = AhoCorasick(patterns)
print(ac.find_matches_as_strings("discontent", overlapping=True))
# ['disco', 'onte', 'discontent']

The find_matches_as_indexes method returns the locations of matches within the haystack. This is useful when you need the exact positions of the patterns.

Signature: find_matches_as_indexes(haystack, overlapping=False)

Returns: A list of tuples: (index_into_patterns, start_index_in_haystack, end_index_in_haystack).

Important Details:

• For string-based AhoCorasick, the indices returned are Unicode code point indices (character indices), not byte indices, making it compatible with Python string slicing.
• If overlapping=True, the method will include overlapping results (e.g., searching for 'ana' in 'banana' would return both matches if overlapping is enabled).
• For BytesAhoCorasick, the indices are byte indices.

from ahocorasick_rs import AhoCorasick

ac = AhoCorasick(["abc", "bcd"])
haystack = "abcd"

# Returns [(0, 0, 3), (1, 1, 4)]
matches = ac.find_matches_as_indexes(haystack, overlapping=True)

Use the AhoCorasick class to search for multiple pattern strings within a single haystack string.

Constructor Signature: AhoCorasick(patterns, matchkind=MatchKind.Standard, store_patterns=None, implementation=None)

Arguments:

• patterns: An iterable of strings. Empty strings are not supported and will raise a ValueError.
• matchkind: Determines how matches are selected. Defaults to MatchKind.Standard.
• store_patterns: If True, the engine keeps references to the patterns, which speeds up find_matches_as_strings() at the cost of higher memory usage. If None, a heuristic is used: patterns totaling up to 4KB are stored; otherwise, they are not.
• implementation: The underlying automaton type (Implementation.NoncontiguousNFA, Implementation.ContiguousNFA, or Implementation.DFA).

Note: If you pass mutable buffers as patterns, do not mutate them in another thread during construction.

from ahocorasick_rs import AhoCorasick, MatchKind, Implementation

patterns = ["apple", "banana", "cherry"]
# Using DFA implementation for faster searching
ac = AhoCorasick(patterns, matchkind=MatchKind.Standard, implementation=Implementation.DFA)

Use BytesAhoCorasick to search for multiple byte patterns within a bytes-like object (e.g., bytes, bytearray, or memoryview).

Constructor Signature: BytesAhoCorasick(patterns, matchkind=MatchKind.Standard, implementation=None)

Arguments:

• patterns: An iterable of bytes-like objects. Empty patterns raise ValueError.
• matchkind: Determines match selection logic.
• implementation: The underlying automaton type (Implementation.NoncontiguousNFA, Implementation.ContiguousNFA, or Implementation.DFA).

Important Safety Warning: If you pass in mutable buffers (like bytearray) as patterns, you MUST NOT mutate them in another thread while the object is being constructed. Once construction is complete, the patterns are no longer referenced, and the buffers can be safely mutated.

Note: Unlike the string-based version, find_matches_as_indexes for BytesAhoCorasick returns byte indices.

from ahocorasick_rs import BytesAhoCorasick, MatchKind

patterns = [b"abc", b"def"]
haystack = b"abcdef"

bac = BytesAhoCorasick(patterns)
matches = bac.find_matches_as_indexes(haystack)