{ "category": "Lookup and reference functions", "display_name": "TOCOL", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.TOCOL", "implementation_state": { "answer_bank": null, "detail": "Recorded: 9 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 9 recorded answers", "workbook_corpus": { "cells": 9, "matched": 9 } }, "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#L683-L689", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/dynamic_array_reshape_family.rs#L479-L495" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/arrays::source_error", "catalogue/arrays::prepared", "catalogue/arrays::prepared_one", "catalogue/arrays::by_area", "catalogue/arrays::result", "catalogue/arrays::run", "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_bool_like", "ported/dynamic_array_reshape_family::build_array", "ported/dynamic_array_reshape_family::flatten_cells", "ported/dynamic_array_reshape_family::should_ignore_cell", "ported/dynamic_array_reshape_family::parse_ignore_mode", "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#L683-L689", "state": "matches", "suite": null, "summary": "Matches all 9 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.TOCOL.json", "name": "TOCOL", "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- **`TOROW`** is the transpose: the same flattening with the same `ignore` and\n `scan_by_column` vocabulary, producing a single row. `TOCOL(x, i, s)` equals\n `TRANSPOSE(TOROW(x, i, s))`.\n- **`WRAPCOLS` / `WRAPROWS`** are the inverse: a vector back to a rectangle.\n- **`TRANSPOSE`** exchanges the axes without flattening.\n- **`FILTER`** removes whole rows by predicate; `TOCOL`'s `ignore` removes individual elements\n by kind. They are not substitutes.\n- **`TRIMRANGE`** removes the blank *margin* of a range; `TOCOL(…, 1)` removes blanks\n everywhere, including interior ones, and destroys the two-dimensional structure while doing\n it.\n- **`VSTACK`** concatenates while preserving structure; flattening a stack is a common\n composition (`TOCOL(VSTACK(a, b), 1)`).\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- Two orthogonal parameters: what to skip, and in what order to walk. Implementing `ignore` as\n a post-filter on an already-built column is correct only if the traversal order was applied\n first — the two commute here, but only because filtering is order-preserving.\n- `ignore` is a code, not a flag. Values outside `0..3` need a decided outcome.\n- The blank definition — empty cell versus empty string versus a formula returning `\"\"` — must\n be stated. It is the single most consequential ambiguity in this function.\n- An empty result is a real case with a specific outcome, not an edge to leave undefined.\n- Scalars and 1×1 arrays flatten to a one-element column, which must stay array-shaped.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind is a single-column array.\n\n- **The result can be empty.** `TOCOL(range, 3)` over a range of only blanks and errors leaves\n nothing. The Excel convention for an empty array result is `#CALC!`\n ([the value universe](../model/01-value-universe.md)), and `TOCOL` uses it:\n `TOCOL({#N/A},2)` drops the error, has nothing left, and is `#CALC!` (FN-HSTACK-001).\n- **What counts as \"blank\".** Whether `ignore` `1` drops empty cells only, or also empty text\n `\"\"`, is the question this function turns on in practice — a column produced by a formula\n chain is usually full of `\"\"`, not of empty cells. The documentation says \"blanks\" and does\n not disambiguate; the Handbook has not verified it.\n- **Ignoring errors removes them entirely**; it does not replace them. The result is shorter,\n which means positions no longer correspond to the source. A direct error is not an element\n and is not ignored: `TOCOL(#N/A,2)` is `#N/A` (FN-HSTACK-001).\n- **A single-element result stays an array.** See the `TAKE` page for the probes that make that\n distinction observable.\n- Dynamic-array publication and `#SPILL!` are host-side adaptation, not `TOCOL` semantics.\n\n\n\n### Errors\n\n\nDocumented by Microsoft on the `TOCOL` page:\n\n| Error | Documented condition |\n|---|---|\n| `#VALUE!` | An array constant containing one or more numbers that are not whole numbers |\n| `#NUM!` | `array` is too large |\n\nThe first of those is worth flagging as unusual: it is stated on Microsoft's page, and it does\nnot obviously describe a flattening operation, whose result should not care whether its\nelements are integers. The Handbook records it as documented and does not attempt to explain\nit; confirming what it actually refers to is one of the open probes below.\n\n\n", "sources": "\n- Microsoft, *TOCOL function* —\n \n (syntax, the four `ignore` values, the `scan_by_column` default and meaning, and the\n documented `#VALUE!` and `#NUM!` conditions). Retrieved for this page.\n- Handbook `content/model/01-value-universe.md` (the `Empty` kind and the `#CALC!` convention)\n and `content/model/03-call-pipeline.md`.\n- Handbook `data/functions/FUNC.TOCOL.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`TOCOL` flattens. It takes an `m × n` array and returns a single column containing its\nelements in a chosen traversal order, optionally dropping some of them.\n\nThe traversal is the substantive parameter. With `scan_by_column` false or omitted, the array\nis read **by row** — left to right along row 1, then row 2, and so on, which is row-major\norder. With `scan_by_column` true, it is read **by column** — top to bottom down column 1, then\ncolumn 2. For the array `{1,2;3,4}` those give `{1;2;3;4}` and `{1;3;2;4}` respectively.\n\nThe `ignore` argument then removes categories of element before the column is assembled:\n\n| `ignore` | Documented meaning |\n|---|---|\n| `0` | Keep all values (default) |\n| `1` | Ignore blanks |\n| `2` | Ignore errors |\n| `3` | Ignore blanks and errors |\n\nThe result length is therefore `m · n` minus whatever was dropped — the one place in this\nfamily where the output size is not a pure function of the input's shape.\n\n`TOCOL(range, 1)` is, in practice, the modern answer to \"give me the non-empty values of this\nrectangle as a list\", which is why it turns up in `UNIQUE`, `SORT` and `TEXTJOIN` pipelines far\nmore often than its documentation suggests.\n\n\n\n### Arguments\n\n\nMicrosoft documents `TOCOL(array, [ignore], [scan_by_column])`.\n\n**`array`** — required. The array or reference to flatten.\n\n**`ignore`** — optional, default `0`. Takes the four values above. Note that it is a small\ninteger code, not a logical: `TOCOL(A1:C9, TRUE)` coerces to `1` and means \"ignore blanks\",\nwhich happens to be a reasonable request but is not what the writer of `TRUE` was thinking.\n\n**`scan_by_column`** — optional, default `FALSE`. A logical. When omitted or `FALSE`, the array\nis scanned by row; when `TRUE`, by column.\n\nThe two optional arguments are the ones readers swap, because both are small and both are\n\"options\". `TOCOL(A, 1)` ignores blanks; `TOCOL(A, , 1)` scans by column. The first is a\nfilter, the second a traversal order, and neither is an error, so a swap produces a\ncorrect-looking column with the wrong contents or the wrong order.\n\n\n" }, "signature": { "display": "TOCOL(array, [ignore], [scan_by_column])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "ignore", "optional": true, "repeats": false }, { "description": null, "name": "scan_by_column", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "min": 1 }, "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": "The items of an array in one column", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the array in a single column", "microsoft_url": "https://support.microsoft.com/en-us/office/tocol-function-22839d9b-0b55-4fc1-b4e6-2761f8f122ed" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "TOCOL" }, { "locale": "bg-BG", "name": "TOCOL" }, { "locale": "cs-CZ", "name": "DO.SLOUPCE" }, { "locale": "da-DK", "name": "TILKOLONNE" }, { "locale": "de-DE", "name": "TOCOL" }, { "locale": "el-GR", "name": "TOCOL" }, { "locale": "en-AU", "name": "TOCOL" }, { "locale": "en-GB", "name": "TOCOL" }, { "locale": "en-US", "name": "TOCOL" }, { "locale": "es-ES", "name": "ENCOL" }, { "locale": "et-EE", "name": "TOCOL" }, { "locale": "fi-FI", "name": "SARAKKEESEEN" }, { "locale": "fr-FR", "name": "DANSCOL*" }, { "locale": "he-IL", "name": "TOCOL" }, { "locale": "hr-HR", "name": "TOCOL" }, { "locale": "hu-HU", "name": "OSZLOPHOZ" }, { "locale": "id-ID", "name": "TOCOL" }, { "locale": "it-IT", "name": "TOCOL" }, { "locale": "ja-JP", "name": "TOCOL" }, { "locale": "ko-KR", "name": "TOCOL" }, { "locale": "lt-LT", "name": "TOCOL" }, { "locale": "lv-LV", "name": "TOCOL" }, { "locale": "nb-NO", "name": "TOCOL" }, { "locale": "nl-NL", "name": "NAAR.KOLOM" }, { "locale": "pl-PL", "name": "DO.KOLUMNY" }, { "locale": "pt-BR", "name": "TOCOL" }, { "locale": "pt-PT", "name": "PARACOL" }, { "locale": "ro-RO", "name": "TOCOL" }, { "locale": "ru-RU", "name": "ПОСТОЛБЦ" }, { "locale": "sk-SK", "name": "TOCOL" }, { "locale": "sl-SI", "name": "TOCOL" }, { "locale": "sr-Latn-RS", "name": "TOCOL" }, { "locale": "sv-SE", "name": "TILLKOL" }, { "locale": "th-TH", "name": "TOCOL" }, { "locale": "tr-TR", "name": "SÜTUNA" }, { "locale": "uk-UA", "name": "TOCOL" }, { "locale": "vi-VN", "name": "TOCOL" }, { "locale": "zh-CN", "name": "TOCOL" }, { "locale": "zh-HK", "name": "TOCOL" }, { "locale": "zh-TW", "name": "TOCOL" } ], "signature": { "display": "TOCOL(array, [ignore], [scan_by_column])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "ignore", "optional": true, "repeats": false }, { "description": null, "name": "scan_by_column", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "TOCOL", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/tocol-function-22839d9b-0b55-4fc1-b4e6-2761f8f122ed" }, "try_it": { "formula": "=TOCOL({1,2;3,4})" }, "url": "https://handbook.dnacalc.com/functions/TOCOL.html", "variants": [], "versions": [ { "behaviour": "=TOCOL(#N/A,2) returned #N/A. =TOCOL({#N/A},2) returned #CALC!. 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": "=TOCOL(#N/A,2)", "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": "=TOCOL({#N/A},2)", "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" } ], "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" ] } ] }