{ "category": "Logical functions", "display_name": "MAP", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.MAP", "implementation_state": { "answer_bank": null, "detail": "Recorded: 35 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 35 recorded answers", "workbook_corpus": { "cells": 35, "matched": 35 } }, "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/lambda_helpers.rs#L449-L449", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lambda_helpers.rs#L110-L142" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/lambda_helpers::prepared", "catalogue/lambda_helpers::lambda", "catalogue/lambda_helpers::item", "catalogue/lambda_helpers::cell", "catalogue/lambda_helpers::items", "catalogue/lambda_helpers::array", "catalogue/lambda_helpers::helper", "catalogue/lambda_helpers::HelperTask::advance", "catalogue/lambda_helpers::run" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lambda_helpers.rs#L449-L449", "state": "matches", "suite": null, "summary": "Matches all 35 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.MAP.json", "name": "MAP", "notes": [ { "basis": "27 recorded readings in dynamic-array Excel, each with size observers.", "documentation": null, "evidence": [ { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "scalar_errors_keep_their_array_argument_origins", "note": "recorded readings pinned", "path": "apps/dna-onecalc/tests/acceptance.rs", "repository": "DnaCalc" }, { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheets fn2_q001 to fn2_q007, fn2_q031 to fn2_q042, fn2_q232 to fn2_q239", "note": "recorded readings", "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } ], "functions": [ "FUNC.BYCOL", "FUNC.BYROW", "FUNC.EXPAND", "FUNC.HSTACK", "FUNC.MAP", "FUNC.TAKE", "FUNC.TOCOL", "FUNC.TOROW", "FUNC.VSTACK" ], "inferred": null, "kind": "quirk", "note_id": "FN-HSTACK-001", "open": [ "Competing errors in later positions have not been read in a published capture." ], "recorded_on": "2026-11-04", "repros": [ { "call": "=HSTACK(1,#VALUE!)", "correct": null, "excel": { "bits": null, "display": "#VALUE!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q004, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=TAKE(#N/A,0)", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q232, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=MAP(NA(),LAMBDA(xx,IFERROR(xx,3)))", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q031, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=MAP({#N/A},LAMBDA(xx,3))", "correct": null, "excel": { "bits": "0x4008000000000000", "display": "3", "kind": "number" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q032, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=HSTACK(Data!C1,{1;2})", "correct": null, "excel": { "bits": null, "display": "{#N/A,1;#N/A,2}", "kind": "array" }, "input_route": "cell-value2", "inputs": [ { "name": "Data!C1", "value": { "bits": null, "display": "#N/A", "kind": "error" } } ], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q238, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=TOCOL(#N/A,2)", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q233, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=TOCOL({#N/A},2)", "correct": null, "excel": { "bits": null, "display": "#CALC!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q234, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=EXPAND(Data!C1,2,2,\"pad\")", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "cell-value2", "inputs": [ { "name": "Data!C1", "value": { "bits": null, "display": "#N/A", "kind": "error" } } ], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q237, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=BYROW(#N/A,#VALUE!)", "correct": null, "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q040, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } }, { "call": "=BYROW({#N/A},2)", "correct": null, "excel": { "bits": null, "display": "#VALUE!", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "source": { "commit": "2d0eddcac86413014643af81d646581d54ba57bc", "locator": "sheet fn2_q038, row 20, column 10", "note": null, "path": "crates/calc-func/tests/captures/fn2_questions/oracle.capture.json", "repository": "DnaCalc" } } ], "schema": "efh.function-note/v1", "statement": "An error written directly as an argument of these functions is the answer for the whole call. It is not placed in the result: HSTACK(1,#VALUE!) is #VALUE!, not a row holding 1 and an error, and TAKE(#N/A,0) is #N/A. With MAP the LAMBDA does not run at all: MAP(NA(),LAMBDA(xx,IFERROR(xx,3))) is #N/A. The same error inside an array, or in a referenced cell, is an ordinary element: MAP({#N/A},LAMBDA(xx,3)) is 3, and HSTACK(Data!C1,{1;2}) with #N/A in Data!C1 is a 2 by 2 array with #N/A in its first column. TOCOL and TOROW show the difference with ignore 2: TOCOL(#N/A,2) is #N/A, while TOCOL({#N/A},2) drops the error, has nothing left, and is #CALC!. EXPAND is an exception on the cell side: EXPAND(Data!C1,2,2,\"pad\") is #N/A for the whole call. BYROW and BYCOL check the direct error first too: BYROW(#N/A,#VALUE!) is #N/A, while BYROW({#N/A},2), where 2 is not a LAMBDA, is #VALUE!.", "status": "measured", "title": "A direct error stops these array functions; the same error in an array or cell is an element" } ], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\nUse an ordinary array expression for a simple elementwise calculation such as squaring. Use\n[BYROW](FUNC.BYROW.md) or [BYCOL](FUNC.BYCOL.md) for whole-row or whole-column calculations.\n[REDUCE](FUNC.REDUCE.md) carries one accumulator through the array; [SCAN](FUNC.SCAN.md) also\nreturns the intermediate accumulators. [MAKEARRAY](FUNC.MAKEARRAY.md) generates values from\nrow and column indices.\n\n\n\n\n", "how-to-implement": "\nSeparate the last argument from the input arrays. Validate the callable and its parameter count\nwithout treating it as a displayed error. For a shared input shape, allocate that output shape\nand visit each coordinate. Read one value from each input at that coordinate, bind the lambda's\nparameters, evaluate its body and store the scalar result at the same coordinate.\n\nKeep direct argument errors distinct from errors held in an array or referenced cell. Passing an\narray element through the lambda is necessary for formulas that deliberately replace errors.\nLikewise, preserve any callable carried inside an array value.\n\nTest mismatched input dimensions, reference inputs, a lambda returning an array, and the order\nof calls to volatile expressions separately. A general array-broadcast rule is not sufficient\nevidence for MAP's shape rule. The recorded examples below settle the direct-error distinction;\nthey do not settle every shape case.\n\n\n", "quirks": "\nMicrosoft documents `#VALUE!` when the final argument is not a valid lambda or its parameter\ncount is wrong. A result must fit one output position; a lambda that returns an array introduces\na separate nested-array problem rather than automatically expanding the result.\n\nA direct error argument and an error inside an array are observably different. On the recorded\nExcel build, `MAP(NA(),LAMBDA(x,IFERROR(x,3)))` returns `#N/A` before invoking the lambda, while\n`MAP({#N/A},LAMBDA(x,3))` returns 3. The array element can reach the lambda even though the same\nerror supplied directly stops the helper.\n\nThe result still needs space in the worksheet. A blocked spill can produce `#SPILL!`; it does\nnot change the array calculation itself. Try it shows the array without placing it in a workbook.\n\n\n", "sources": "\n- [Microsoft: MAP function](https://support.microsoft.com/en-us/excel/functions/map-function).\n- [Recorded helper-function error examples](../notes/FN-HSTACK-001.json).\n\n", "try-it": "\nSquare the example column, then change `x*x` to `IF(x>1,x*x,0)`. Use arrays with the same shape\nwhen adapting the two-input example. Mismatched shapes need their own compatibility checks.\n\n\n", "version-differences": "\nMicrosoft lists MAP for Microsoft 365 and Excel 2024 on Windows and Mac. The build-specific\nobservations below concern error handling. They do not establish that older or later builds\nshare every helper-function rule.\n\n\n", "what-it-does": "\n`MAP(array1, [array2, …], lambda)` applies a calculation to corresponding positions of one or\nmore arrays and returns the resulting array. The lambda goes last and takes one parameter per\ninput array.\n\n`=MAP({1;2;3},LAMBDA(x,x*x))` returns a column containing 1, 4 and 9.\nWith two equally shaped arrays, `=MAP({1;2},{10;20},LAMBDA(x,y,x+y))` returns 11 and 22.\nPositions are paired; MAP does not form every possible pair of inputs.\n\n\n" }, "signature": { "display": "MAP(array1, [array2, …], lambda)", "parameters": [ { "description": "One or more input arrays, all before the final lambda.", "name": "array", "optional": false, "repeats": true }, { "description": "One parameter per input array.", "name": "lambda", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 254, "min": 2 }, "category": "Logical functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "ReductionFold", "fec_dependency_profile": "None", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "An array of the results of a LAMBDA applied to each item of the given arrays", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns an array formed by mapping each value in the array(s) to a new value by applying a LAMBDA to create a new value", "microsoft_url": "https://support.microsoft.com/en-us/office/map-function-48006093-f97c-47c1-bfcc-749263bb1f01" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "MAP" }, { "locale": "bg-BG", "name": "MAP" }, { "locale": "cs-CZ", "name": "MAPA" }, { "locale": "da-DK", "name": "TILKNYT" }, { "locale": "de-DE", "name": "MAP" }, { "locale": "el-GR", "name": "MAP" }, { "locale": "en-AU", "name": "MAP" }, { "locale": "en-GB", "name": "MAP" }, { "locale": "en-US", "name": "MAP" }, { "locale": "es-ES", "name": "MAPEAR" }, { "locale": "et-EE", "name": "MAP" }, { "locale": "fi-FI", "name": "MAP" }, { "locale": "fr-FR", "name": "MAP*" }, { "locale": "he-IL", "name": "MAP" }, { "locale": "hr-HR", "name": "MAP" }, { "locale": "hu-HU", "name": "MAP" }, { "locale": "id-ID", "name": "MAP" }, { "locale": "it-IT", "name": "MAP" }, { "locale": "ja-JP", "name": "MAP" }, { "locale": "ko-KR", "name": "MAP" }, { "locale": "lt-LT", "name": "MAP" }, { "locale": "lv-LV", "name": "MAP" }, { "locale": "nb-NO", "name": "TILORDNE" }, { "locale": "nl-NL", "name": "TOEWIJZING" }, { "locale": "pl-PL", "name": "MAPA" }, { "locale": "pt-BR", "name": "MAPA" }, { "locale": "pt-PT", "name": "MAPA" }, { "locale": "ro-RO", "name": "MAP" }, { "locale": "ru-RU", "name": "MAP" }, { "locale": "sk-SK", "name": "MAP" }, { "locale": "sl-SI", "name": "MAP" }, { "locale": "sr-Latn-RS", "name": "MAP" }, { "locale": "sv-SE", "name": "MAP" }, { "locale": "th-TH", "name": "MAP" }, { "locale": "tr-TR", "name": "EŞLE" }, { "locale": "uk-UA", "name": "MAP" }, { "locale": "vi-VN", "name": "MAP" }, { "locale": "zh-CN", "name": "MAP" }, { "locale": "zh-HK", "name": "MAP" }, { "locale": "zh-TW", "name": "MAP" } ], "signature": { "display": "MAP(array1, lambda_or_array2, ...)", "parameters": [ { "description": null, "name": "array1", "optional": false, "repeats": false }, { "description": null, "name": "lambda_or_array2", "optional": false, "repeats": true } ], "trailing_repeats": true }, "surface_name": "MAP", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/map-function-48006093-f97c-47c1-bfcc-749263bb1f01" }, "try_it": { "formula": "=MAP({1;2;3},LAMBDA(x,x*x))" }, "url": "https://handbook.dnacalc.com/functions/MAP.html", "variants": [], "versions": [ { "behaviour": "=MAP(NA(),LAMBDA(xx,IFERROR(xx,3))) returned #N/A. =MAP({#N/A},LAMBDA(xx,3)) returned 3 (0x4008000000000000). Inputs were supplied through formula literals. These are controls from this environment, not a same-input comparison with another build.", "excel_build": "16.0.20527.20088", "observations": [ { "call": "=MAP(NA(),LAMBDA(xx,IFERROR(xx,3)))", "excel": { "bits": null, "display": "#N/A", "kind": "error" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" }, { "call": "=MAP({#N/A},LAMBDA(xx,3))", "excel": { "bits": "0x4008000000000000", "display": "3", "kind": "number" }, "input_route": "formula-literal", "inputs": [], "recorded_in": "Excel 16.0.20527.20088 Current Channel, Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA" } ], "platform": "Windows 64-bit (NT 10.0.26200), x86-64, AMD Ryzen 7 4800H, en-ZA", "sources": [ "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/3345a87/content/notes/FN-HSTACK-001.json" ] } ] }