ExCellerate.Functions.General.Match (excellerate v0.4.0)

Copy Markdown View Source

Searches for a value in a list and returns its 0-based position.

Inspired by Excel's MATCH function. The optional match_type argument controls the matching behaviour:

  • 0 (default) — exact match; the list can be in any order.
  • 1 — finds the position of the largest value that is less than or equal to lookup_value. The list must be in ascending order.
  • -1 — finds the position of the smallest value that is greater than or equal to lookup_value. The list must be in descending order.

Returns null when no match is found (instead of an error, consistent with ExCellerate's nil-propagation philosophy).

Examples

match('Oranges', fruits)              → 1  (exact match, 0-based)
match(25, sorted_values, 1)           → position of largest value <= 25
match(25, desc_values, -1)            → position of smallest value >= 25
match('missing', items)               → null