{ "category": "Lookup and reference functions", "display_name": "MATCH", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.MATCH", "implementation_state": { "answer_bank": { "excel_builds": [ "20527" ], "larger_numeric": 0, "last_bit": 0, "matched": 13, "other_mismatch": 0, "refused": 0, "rows": 13, "unread": 0, "worst_ulp": 0 }, "detail": "Recorded: 13 in the answer bank and 143 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 156 recorded answers", "workbook_corpus": { "cells": 144, "matched": 143, "pending": 1 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L119-L129", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L892-L919", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L1143-L1155", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L1157-L1191" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/comparison::texts", "catalogue/comparison/collation::compare", "catalogue/comparison/collation::weighed", "catalogue/comparison/collation::measured_iteration_extension", "catalogue/comparison/sort_key::table", "catalogue/comparison/sort_key::decode64", "catalogue/comparison/sort_key::Reader::byte", "catalogue/comparison/sort_key::Reader::varint", "catalogue/comparison/sort_key::Reader::done", "catalogue/comparison/sort_key::in_ranges", "catalogue/comparison/sort_key::build", "catalogue/comparison/sort_key::han_base", "catalogue/comparison/sort_key::derive", "catalogue/comparison/sort_key::shared_jamo_tails", "catalogue/comparison/sort_key::ordinary_jamo_prefix", "catalogue/comparison/sort_key::independent_jamo_suffix", "catalogue/comparison/sort_key::jamo_leading_primary", "catalogue/comparison/sort_key::leading_order", "catalogue/comparison/sort_key::Before::separate_special", "catalogue/comparison/sort_key::Gathered::kana", "catalogue/comparison/sort_key::Gathered::unit", "catalogue/comparison/sort_key::parts", "catalogue/comparison/sort_key::diacritic_order", "catalogue/comparison/sort_key::diacritics", "catalogue/lookup::eager", "catalogue/lookup::Item::rank", "catalogue/lookup::item", "catalogue/lookup::lookup_key", "catalogue/lookup::text_limit", "catalogue/lookup::equal", "catalogue/lookup::error_rank", "catalogue/lookup::order", "catalogue/lookup::pattern", "catalogue/lookup::matches", "catalogue/lookup::hits", "catalogue/lookup::Line::len", "catalogue/lookup::Line::scan", "catalogue/lookup::Line::held", "catalogue/lookup::reader", "catalogue/lookup::cell_value", "catalogue/lookup::rows", "catalogue/lookup::columns", "catalogue/lookup::row_line", "catalogue/lookup::column_line", "catalogue/lookup::line", "catalogue/lookup::value", "catalogue/lookup::span", "catalogue/lookup::shape", "catalogue/lookup::first_hit", "catalogue/lookup::bisect", "catalogue/lookup::index_number", "catalogue/lookup::position", "catalogue/lookup::index", "catalogue/lookup::selector", "catalogue/lookup::indexed", "catalogue/lookup::select", "catalogue/lookup::row", "catalogue/lookup::column", "catalogue/lookup::position_of", "catalogue/lookup::areas" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L119-L129", "state": "matches", "suite": null, "summary": "Matches all 156 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.MATCH.json", "name": "MATCH", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n- **`XMATCH` supersedes `MATCH`.** `XMATCH` keeps the position-returning shape but splits the\n single `match_type` flag into an explicit `match_mode` and `search_mode`, defaults to exact\n match rather than ordered match, and adds reverse and binary search. For new work `XMATCH`\n is the better choice. Microsoft has not deprecated `MATCH`; it remains supported and remains\n what existing workbooks contain.\n- **`INDEX`** is `MATCH`'s usual partner: `INDEX(R, MATCH(v, L, 0))` is the classic\n exact-lookup composition, and it is what `XLOOKUP` packages into one call.\n- **`LOOKUP`** shares the ordered-search rule with `match_type` `1` and has no exact mode.\n- Readers confuse `MATCH` with `FIND` and `SEARCH` (which locate a substring inside one text\n value, not a value inside a list).\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- Three `match_type` values are two different algorithms: an unordered scan for `0`, and an\n ordered search for `±1`. Sharing one code path between them is how implementations acquire\n the wrong behaviour on unsorted input.\n- Exact mode is case-insensitive but numerically strict. Those two facts pull in opposite\n directions and are easy to implement inconsistently.\n- Wildcard handling belongs to exact mode only, and `~` escaping has to be handled before\n pattern compilation, not after.\n- `lookup_value` must admit arrays and spill elementwise.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is a number: a 1-based index into `lookup_array`.\n\n- **Case-insensitivity.** Microsoft states plainly that `MATCH` does not distinguish uppercase\n from lowercase. Exact mode is therefore *not* string identity.\n- Errors, empty cells and omitted arguments follow the shared rules in\n [coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n\n### Errors\n\n\nDocumented: `#N/A` when no match is found. Under `match_type` `1` that includes the case where\n`v` is smaller than every entry; under `-1`, where `v` is larger than every entry.\n\n", "sources": "- Microsoft, *MATCH function* —\n \n (syntax, the three `match_type` rules and their sort requirements, the explicit ascending\n order including text and logicals, case-insensitivity, wildcard support, and `#N/A`).\n Retrieved for this page.\n- Handbook `content/model/02-coercion-and-lifting.md` and `content/model/03-call-pipeline.md`.\n- Handbook `data/functions/FUNC.MATCH.json` (signature, arity, classification axes).\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`MATCH` returns a **position, not a value**. Given a lookup value `v` and a one-dimensional\nlookup array `L` with entries `L[1] … L[n]`, it returns an index `i ∈ 1..n` chosen by the\n`match_type` rule, or `#N/A`.\n\nThe three rules, as Microsoft documents them:\n\n| `match_type` | Rule | Sort requirement |\n|---|---|---|\n| `1` (default) | the largest value that is less than or equal to `v` | `L` ascending |\n| `0` | the first value exactly equal to `v` | none |\n| `-1` | the smallest value that is greater than or equal to `v` | `L` descending |\n\nTwo of the three rules therefore carry a caller obligation that Excel does not check. The\n`1` and `-1` rules are *ordered* searches: they are only meaningful over a sorted array, and\nExcel raises no error when the array is not sorted — it returns a deterministic index computed\nunder a false premise.\n\nMicrosoft's documentation also states the sort order it means, which is unusually explicit and\nworth quoting structurally rather than paraphrasing: ascending order is given as\n`-2, -1, 0, 1, 2, …, A-Z, FALSE, TRUE`. That is a **cross-type total order**: all numbers\nprecede all text, text precedes `FALSE`, and `FALSE` precedes `TRUE`. This is the ordering an\nordered `MATCH` compares against when the array mixes types, and it is the same ordering that\ngoverns the older approximate lookups.\n\nThe index returned is relative to `L`, not to the worksheet. `MATCH(v, A5:A9, 0)` returning\n`2` means `A6` — the caller adds the offset. That is why `MATCH` is almost always seen inside\n`INDEX`, which does the arithmetic.\n\n\n\n### Arguments\n\n\n**`lookup_value`** — the value to find. May be a number, text, a logical, or a reference to\none. In exact mode (`match_type` `0`) a text lookup value may contain wildcards: `?` matches\nany single character, `*` matches any run of characters, and `~` escapes a literal `?`, `*` or\n`~`. Wildcards are documented only for `match_type` `0`.\n\n**`lookup_array`** — the sequence to search. Conventionally a single row or single column.\nWhat `MATCH` does with a genuinely two-dimensional array is not stated in the documentation\nand is not asserted here.\n\n**`match_type`** — optional, **defaults to `1`**. This default deserves the same suspicion as\n`VLOOKUP`'s omitted fourth argument, for the same reason: omitting it selects an *ordered*\nsearch whose failure on unsorted data is a plausible wrong index rather than an error. A\nreader who writes `MATCH(v, L)` meaning \"where is `v`\" has written \"where is the last entry not\nexceeding `v`, assuming `L` is sorted ascending\". Pass `0` explicitly when you mean exact.\n\n\n" }, "signature": { "display": "MATCH(lookup_value, lookup_array, [match_type])", "parameters": [ { "description": null, "name": "lookup_value", "optional": false, "repeats": false }, { "description": null, "name": "lookup_array", "optional": false, "repeats": false }, { "description": null, "name": "match_type", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 2 }, "category": "Lookup and reference functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "LookupMatchProfile", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "RefOnly", "host_interaction_class": "None", "kernel_signature_class": "LookupMatch", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "Position of a value within a row or column", "short_source": "dna-calc-own" }, "docs": { "english_description": "Looks up values in a reference or array", "microsoft_url": "https://support.microsoft.com/en-us/office/match-function-e8dffd45-c762-47d6-bf89-533f4a37673a" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "MATCH" }, { "locale": "bg-BG", "name": "MATCH" }, { "locale": "cs-CZ", "name": "MATCH" }, { "locale": "da-DK", "name": "MATCH" }, { "locale": "de-DE", "name": "MATCH" }, { "locale": "el-GR", "name": "MATCH" }, { "locale": "en-AU", "name": "MATCH" }, { "locale": "en-GB", "name": "MATCH" }, { "locale": "en-US", "name": "MATCH" }, { "locale": "es-ES", "name": "MATCH" }, { "locale": "et-EE", "name": "MATCH" }, { "locale": "fi-FI", "name": "VASTINE" }, { "locale": "fr-FR", "name": "MATCH" }, { "locale": "he-IL", "name": "MATCH" }, { "locale": "hr-HR", "name": "MATCH" }, { "locale": "hu-HU", "name": "MATCH" }, { "locale": "id-ID", "name": "MATCH" }, { "locale": "it-IT", "name": "CONFRONTA" }, { "locale": "ja-JP", "name": "MATCH" }, { "locale": "ko-KR", "name": "MATCH" }, { "locale": "lt-LT", "name": "MATCH" }, { "locale": "lv-LV", "name": "MATCH" }, { "locale": "nb-NO", "name": "MATCH" }, { "locale": "nl-NL", "name": "MATCH" }, { "locale": "pl-PL", "name": "MATCH" }, { "locale": "pt-BR", "name": "MATCH" }, { "locale": "pt-PT", "name": "MATCH" }, { "locale": "ro-RO", "name": "MATCH" }, { "locale": "ru-RU", "name": "MATCH" }, { "locale": "sk-SK", "name": "MATCH" }, { "locale": "sl-SI", "name": "MATCH" }, { "locale": "sr-Latn-RS", "name": "MATCH" }, { "locale": "sv-SE", "name": "MATCH" }, { "locale": "th-TH", "name": "MATCH" }, { "locale": "tr-TR", "name": "KAÇINCI" }, { "locale": "uk-UA", "name": "MATCH" }, { "locale": "vi-VN", "name": "MATCH" }, { "locale": "zh-CN", "name": "MATCH" }, { "locale": "zh-HK", "name": "MATCH" }, { "locale": "zh-TW", "name": "MATCH" } ], "signature": { "display": "MATCH(lookup_value, lookup_array, [match_type])", "parameters": [ { "description": null, "name": "lookup_value", "optional": false, "repeats": false }, { "description": null, "name": "lookup_array", "optional": false, "repeats": false }, { "description": null, "name": "match_type", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "MATCH", "version_marker": null, "xlcall": { "code": "64", "symbol": "xlfMatch" } }, "microsoft": "https://support.microsoft.com/en-us/office/match-function-e8dffd45-c762-47d6-bf89-533f4a37673a" }, "try_it": { "formula": "=MATCH(2,{1;2;3},0)" }, "url": "https://handbook.dnacalc.com/functions/MATCH.html", "variants": [], "versions": [] }