{ "category": "Lookup and reference functions", "display_name": "EXPAND", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.EXPAND", "implementation_state": { "answer_bank": null, "detail": "Recorded: 23 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 23 recorded answers", "workbook_corpus": { "cells": 23, "matched": 23 } }, "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/arrays.rs#L703-L725", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/dynamic_array_reshape_family.rs#L417-L450" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/arrays::source_error", "catalogue/arrays::prepared_one", "catalogue/arrays::result", "catalogue/arrays::as_array", "ported/dynamic_array_reshape_family::coerce_prepared_to_number", "ported/dynamic_array_reshape_family::scalar_cell", "ported/dynamic_array_reshape_family::materialize_array_arg", "ported/dynamic_array_reshape_family::shape", "ported/dynamic_array_reshape_family::get", "ported/dynamic_array_reshape_family::parse_integer", "ported/dynamic_array_reshape_family::parse_positive_integer", "ported/dynamic_array_reshape_family::build_array", "ported/dynamic_array_reshape_family::map_dynamic_array_reshape_error_to_ws" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/arrays.rs#L703-L725", "state": "matches", "suite": null, "summary": "Matches all 23 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.EXPAND.json", "name": "EXPAND", "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": "\n### Relationships\n\n\n- **`TAKE` and `DROP`** shrink where `EXPAND` grows, but note the argument-convention difference\n described above: their counts are increments, `EXPAND`'s are targets.\n- **`HSTACK` and `VSTACK`** pad implicitly with `#N/A` when the pieces do not conform. `EXPAND`\n makes that padding explicit and lets you choose the fill value — which is the usual reason to\n reach for it before stacking.\n- **`IFERROR`** is the standard partner when the `#N/A` default is not wanted after the fact;\n supplying `pad_with` is the cheaper alternative.\n- **`SEQUENCE`** builds an array of a target shape from nothing; `EXPAND` reshapes one you have.\n- **`MAKEARRAY`** and the `LAMBDA` helpers construct padded results generatively, which is the\n route to take when the pad value depends on position rather than being constant.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **The pad region is an L, not a rectangle.** Growing both axes creates three new regions\n (right, below, bottom-right). Implementations that fill row-major over the whole output and\n copy the original in afterwards get this right by construction; implementations that fill\n \"the new rows\" and \"the new columns\" separately double-fill or miss the corner.\n- **Validate before allocating.** The documented `#VALUE!` condition — a target smaller than the\n current extent — must be checked before any output buffer is sized, or a shrink request\n becomes a truncation bug.\n- **`pad_with` must be copied as a value of any kind**, including error values, without\n coercion. An implementation that types the fill as a number cannot express the documented\n default.\n- **Large targets are a resource question.** `EXPAND` is the easiest function in the family to\n ask for an enormous result from, since the size is an argument rather than derived from the\n input. Whatever ceiling the host imposes is the host's, not this function's, and the Handbook\n has not established what Excel does at that ceiling.\n- The module is shared with the rest of the dynamic-array reshapers.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturn kind: `Array`, of exactly the requested dimensions. The result spills; spilling is\nhost-side adaptation ([the call pipeline](../model/03-call-pipeline.md)).\n\n- **`rows` or `columns` equal to the current extent** is a no-op on that axis.\n- **`pad_with` may be any scalar**: a number, text, a logical, or an error value. Passing `\"\"`\n is the common way to get visually blank padding, and it produces empty *text*, not the Empty\n kind — [the value universe](../model/01-value-universe.md) keeps those distinct, and\n downstream `ISBLANK` will disagree with your eyes.\n- **Whether `pad_with` may be an array** is not established here. If it can, the padding\n semantics are no longer \"one value everywhere\".\n- **Element errors** inside an array in `array` pass through unchanged; nothing collapses\n (`error_collapse_profile: None`). An error written directly, or held in a single referenced\n cell, is the answer for the whole call: `EXPAND(Data!C1,2,2,\"pad\")` with `#N/A` in `Data!C1` is\n `#N/A` (FN-HSTACK-001).\n\n\n\n### Errors\n\n\nMicrosoft's page documents that `EXPAND` returns `#VALUE!` when `rows` or `columns` is smaller\nthan the array's current row or column count. That is the characteristic error of this function\nand it follows from its one-directional design: there is no shrinking mode to fall back on.\n\nThe documented default `pad_with` of `#N/A` means an ordinary successful `EXPAND` routinely\n*contains* error values without *being* an error. That distinction matters downstream: an\naggregate scanning the padded result will meet `#N/A` and, under the propagation rule in\n[coercion and lifting](../model/02-coercion-and-lifting.md), surface it. Supplying an explicit\n`pad_with` — `0`, `\"\"` — is usually what a formula that feeds an aggregate actually wants.\n\nAn error value supplied as `rows` or `columns` propagates by the same universal rule.\n\n\n", "sources": "\n- Microsoft, EXPAND function —\n \n (target `rows` and `columns`, the `#N/A` default for `pad_with`, and the `#VALUE!` condition\n when a target is smaller than the current extent).\n- Handbook `content/model/01-value-universe.md` (error values as first-class values; empty text\n versus Empty).\n- Handbook `content/model/02-coercion-and-lifting.md` (error propagation).\n- Handbook `content/model/03-call-pipeline.md` (`ByIndexScalarArrayLift`; host-side spill\n adaptation).\n- Handbook `data/functions/FUNC.EXPAND.json` and `data/presence/FUNC.EXPAND.json` (arity,\n classification axes, shared reshape-family module).\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`EXPAND(array, rows, [columns], [pad_with])` returns an array of the requested dimensions whose\ntop-left region is `array` and whose remaining cells are all `pad_with`.\n\nThe operation is one-directional: it grows, it never shrinks. The original elements keep their\npositions relative to the top-left corner, and every new cell — to the right, below, and in the\nbottom-right corner block — receives the same pad value. Microsoft documents the default\n`pad_with` as `#N/A`, which is a deliberate choice rather than a convenience: `#N/A` is the\nvalue model's \"not available\" marker, so an unpadded `EXPAND` produces a result whose synthetic\ncells announce themselves rather than masquerading as zeros or blanks.\n\n`EXPAND` is the growing complement of `TAKE`/`DROP` and the shape-fixing tool for the whole\ndynamic-array family: when two arrays must be conformable — for `HSTACK` alignment, for an\nelementwise operation, for a fixed-size output block — `EXPAND` is how you make them so\nexplicitly instead of relying on broadcasting.\n\n\n\n### Arguments\n\n\n| Argument | Meaning |\n|---|---|\n| `array` | The array or range to pad. Required. |\n| `rows` | The number of rows the result should have. Required. |\n| `columns` | The number of columns the result should have. Optional; omitted keeps the array's current column count. |\n| `pad_with` | The value to fill new cells with. Optional; Microsoft documents the default as `#N/A`. |\n\nTwo positions are commonly misread.\n\n**`rows` and `columns` are target dimensions, not increments.** `EXPAND(a, 3)` means \"make it\nthree rows tall\", not \"add three rows\". This is the opposite convention from `DROP` and `TAKE`,\nwhose counts *are* increments, and the inconsistency is the most reliable source of error when\nthe two are used in the same formula.\n\n**Omitting `columns` is not the same as passing the current width** in one respect: it is\nshorter and it tracks a changing input, but the documented effect is the same — the column axis\nis left as it is. Passing an explicit width smaller than the current width is an error, not a\ntruncation.\n\n\n" }, "signature": { "display": "EXPAND(array, rows, [columns], [pad_with])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "rows", "optional": false, "repeats": false }, { "description": null, "name": "columns", "optional": true, "repeats": false }, { "description": null, "name": "pad_with", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 4, "min": 2 }, "category": "Lookup and reference functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "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 padded out to a given number of rows and columns", "short_source": "dna-calc-own" }, "docs": { "english_description": "Expands or pads an array to specified row and column dimensions", "microsoft_url": "https://support.microsoft.com/en-us/office/expand-function-7433fba5-4ad1-41da-a904-d5d95808bc38" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "EXPAND" }, { "locale": "bg-BG", "name": "EXPAND" }, { "locale": "cs-CZ", "name": "ROZBALIT" }, { "locale": "da-DK", "name": "UDVID" }, { "locale": "de-DE", "name": "EXPAND" }, { "locale": "el-GR", "name": "EXPAND" }, { "locale": "en-AU", "name": "EXPAND" }, { "locale": "en-GB", "name": "EXPAND" }, { "locale": "en-US", "name": "EXPAND" }, { "locale": "es-ES", "name": "EXPANDIR" }, { "locale": "et-EE", "name": "EXPAND" }, { "locale": "fi-FI", "name": "LAAJENNA" }, { "locale": "fr-FR", "name": "ÉTENDRE*" }, { "locale": "he-IL", "name": "EXPAND" }, { "locale": "hr-HR", "name": "EXPAND" }, { "locale": "hu-HU", "name": "KITERJESZT" }, { "locale": "id-ID", "name": "EXPAND" }, { "locale": "it-IT", "name": "EXPAND" }, { "locale": "ja-JP", "name": "EXPAND" }, { "locale": "ko-KR", "name": "EXPAND" }, { "locale": "lt-LT", "name": "EXPAND" }, { "locale": "lv-LV", "name": "EXPAND" }, { "locale": "nb-NO", "name": "UTVID" }, { "locale": "nl-NL", "name": "UITBREIDEN" }, { "locale": "pl-PL", "name": "ROZSZERZ" }, { "locale": "pt-BR", "name": "EXPANDIR" }, { "locale": "pt-PT", "name": "EXPANDIR" }, { "locale": "ro-RO", "name": "EXPAND" }, { "locale": "ru-RU", "name": "РАЗВЕРНУТЬ" }, { "locale": "sk-SK", "name": "EXPAND" }, { "locale": "sl-SI", "name": "EXPAND" }, { "locale": "sr-Latn-RS", "name": "RAZVIJ" }, { "locale": "sv-SE", "name": "EXPANDERA" }, { "locale": "th-TH", "name": "EXPAND" }, { "locale": "tr-TR", "name": "GENİŞLET" }, { "locale": "uk-UA", "name": "EXPAND" }, { "locale": "vi-VN", "name": "EXPAND" }, { "locale": "zh-CN", "name": "EXPAND" }, { "locale": "zh-HK", "name": "EXPAND" }, { "locale": "zh-TW", "name": "EXPAND" } ], "signature": { "display": "EXPAND(array, rows, [columns], [pad_with])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "rows", "optional": false, "repeats": false }, { "description": null, "name": "columns", "optional": true, "repeats": false }, { "description": null, "name": "pad_with", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "EXPAND", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/expand-function-7433fba5-4ad1-41da-a904-d5d95808bc38" }, "try_it": { "formula": "=EXPAND({1,2},2,3,0)" }, "url": "https://handbook.dnacalc.com/functions/EXPAND.html", "variants": [], "versions": [ { "behaviour": "=EXPAND(Data!C1,2,2,\"pad\") returned #N/A. Inputs were supplied through cells using Value2. These are controls from this environment, not a same-input comparison with another build.", "excel_build": "16.0.20527.20088", "observations": [ { "call": "=EXPAND(Data!C1,2,2,\"pad\")", "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" } ], "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" ] } ] }