Comparison Modes

This page explains the different comparison modes used internally by CmpStr for string similarity calculations. Understanding these modes helps clarify how the API processes input data and produces results, especially when working with arrays, batch operations, or asynchronous workflows.

Overview

CmpStr supports three distinct comparison modes, which define how input data is combined and evaluated:

• single – Compares one source string with one target string.
• batch – Compares all combinations of source and target strings (cross product).
• pairwise – Compares source and target strings element-wise by index.

The comparison mode is not configured explicitly. Instead, it is inferred automatically from the API method being called and the structure of the provided input data.

Single Mode

Single mode is used when both the source and the target are individual strings. Exactly one comparison is performed and a single result is returned.

Triggered by:

• test( a: string, b: string, opt? )
• compare( a: string, b: string, opt? )
• (all corresponding async methods)

Behavior:

• One comparison only.
• Returns a single similarity value or result object.
• Ideal for direct, one-to-one string comparisons.

Batch Mode

Batch mode is used when at least one input is an array. In this mode, CmpStr computes the cross product of all source and target values.

Triggered by:

• batchTest( a: MetricInput, b: MetricInput, opt? )
• batchSorted( a: MetricInput, b: MetricInput, opt? )
• match( a: MetricInput, b: MetricInput, threshold, opt? )
• closest( a: MetricInput, b: MetricInput, n, opt? )
• furthest( a: MetricInput, b: MetricInput, n, opt? )
• matrix( input: string[], opt? )
• (all corresponding async methods)

Behavior:

• Every source string is compared with every target string.
• The number of comparisons equals source.length × target.length.
• Results are returned as an array of result objects.
• Suitable for search, ranking, clustering, and similarity matrices.

Pairwise Mode

Pairwise mode can be used when both inputs are arrays of equal length. Each source string will be compared only with the target string at the same index.

Triggered by:

• pairs( a: MetricInput, b: MetricInput, opt? )
• pairsAsync( a: MetricInput, b: MetricInput, opt? )

Behavior:

• One comparison per index.
• The number of comparisons equals the array length.
• Each result corresponds to (a[i], b[i]).
• If the input arrays differ in length, an error is thrown.

Notes

• All comparison modes are available in both synchronous and asynchronous APIs.
• Result formats are consistent across modes:
  • Single mode returns a single result.
  • Batch and pairwise modes return arrays of results.
• Mode selection is entirely automatic and based on method signature and input types.

For detailed information on individual functions and return structures, refer to the API Reference.