Skip to main content

​
Overview

The searchAndReplace function takes a trie data structure and a text string as inputs and searches the text for words that match any of the sources described in the trie. When a match is found, it replaces the word in the text with the corresponding target word from the trie.

​
Function signature

searchAndReplace(trie: TrieNode, text: string, searchOptions?: SearchAndReplaceOptions): string

​
Parameters

​
trie
TrieNode
required
The trie data structure constructed using the buildTrie function. This trie contains the rules for search and replacement operations.
​
text
string
required
The input text to search and replace. The function will scan this text for matches against the trie.
​
searchOptions
SearchAndReplaceOptions
Optional configurations for search and replace behavior:

​
Returns

​
result
string
The modified text after replacements. A new string with all occurrences of the source words replaced by their corresponding target words as defined by the rules in the trie.

​
Example usage

​
Basic usage

import { buildTrie, searchAndReplace } from 'trie-rules';

// Define your rules
const rules = [
  {
    from: ["Ka'bah"],
    to: 'Kaʿbah',
  },
];

// Build the trie from the rules with apostrophe normalization
const trie = buildTrie(rules, { normalizeApostrophes: true });

// The text you want to process
const text = 'We visited the Ka`bah yesterday.';

// Perform the search and replace operation
const replacedText = searchAndReplace(trie, text);

console.log(replacedText);
// Output: 'We visited the Kaʿbah yesterday.'

​
With confirmation callback

import { buildTrie, searchAndReplace } from 'trie-rules';

const rules = [
  {
    to: 'Mālik',
    from: ['Maalik', 'Malik'],
    options: { 
      match: 'whole', 
      confirm: { anyOf: ['مالك', 'مَالِكٍ', 'مَالِكٌ'] } 
    },
  },
];

const trie = buildTrie(rules);
const text = 'Maalik went home. مالك';

// Only replace if Arabic text is present
const confirmCallback = (options) => 
  options.anyOf.some((word) => text.includes(word));

const replacedText = searchAndReplace(trie, text, { confirmCallback });

console.log(replacedText);
// Output: 'Mālik went home. مالك'

​
With logging

import { buildTrie, searchAndReplace } from 'trie-rules';

const rules = [
  {
    from: ['example'],
    to: 'demo',
  },
];

const trie = buildTrie(rules);
const text = 'This is an example.';

const replacedText = searchAndReplace(trie, text, {
  log: ({ node }) => {
    console.log('Matched node:', node.target);
  },
});

// Output: Matched node: demo
// Result: 'This is an demo.'

​
Behavior details

​
Apostrophe normalization

If the trie was built with normalizeApostrophes: true, the search operation will automatically treat all apostrophe-like characters (’, ’, `, ʾ, ʿ) as equivalent to the standard apostrophe (’) for matching purposes.

​
Match precedence

When multiple patterns can match at the same position, the function prioritizes longer matches over shorter ones by tracking the last valid match and continuing to search for potentially longer matches.

​
Clipping behavior

The function handles clipping adjustments for rules that specify clipStartPattern or clipEndPattern options, removing specified characters immediately before or after the match.

​
Runtime complexity

The complexity is O(l · k) in the worst case, where:
  • l = length of the text to search through
  • k = average length of source words
In average and best-case scenarios, performance is closer to O(l) since the trie structure allows for quick elimination of non-matching paths.

Build docs developers (and LLMs) love

Get started for freeTalk to us