{ "category": "Logical functions", "display_name": "BYCOL", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.BYCOL", "implementation_state": { "answer_bank": null, "detail": "Recorded: 32 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 32 recorded answers", "workbook_corpus": { "cells": 32, "matched": 32 } }, "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#L453-L453", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lambda_helpers.rs#L240-L246" ], "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::array", "catalogue/lambda_helpers::by_task", "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#L453-L453", "state": "matches", "suite": null, "summary": "Matches all 32 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.BYCOL.json", "name": "BYCOL", "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[BYROW](FUNC.BYROW.md) applies a lambda to rows and returns a column. [MAP](FUNC.MAP.md) visits\nindividual positions and preserves the input shape. A direct SUM of a single column is shorter\nwhen only one column needs aggregating.\n\n\n\n\n", "how-to-implement": "\nRetain the input's two-dimensional shape. For each column, expose a column-shaped view to the\ncallable, bind its one parameter, evaluate the body and store its scalar answer in that column\nof a one-row output. Avoid copying the whole input for every invocation.\n\nPreserve references where the callable's operation needs them. Detect direct argument errors\nat the appropriate stage, then validate the callable and its arity. Reject nested-array results\nthrough the helper's result rule rather than flattening them silently. Keep errors returned as\nindividual scalar results in their output positions.\n\n\n", "quirks": "\nThe lambda must accept one parameter and produce one result per column. Microsoft's documented\nerrors distinguish incorrect parameters (`#VALUE!`) from failure to produce a single value\n(`#CALC!`). BYCOL does not create a row of nested arrays.\n\nA direct error can stop the helper before its lambda is checked. On the recorded build,\n`BYCOL(#N/A,#VALUE!)` is `#N/A`, while `BYCOL({#N/A},2)` is `#VALUE!`. The latter supplies an\narray element but no valid lambda. This distinction matters when validating arguments.\n\n\n", "sources": "\n- [Microsoft: BYCOL function](https://support.microsoft.com/en-us/excel/functions/bycol-function).\n- [Recorded helper error examples](../notes/FN-HSTACK-001.json).\n\n", "try-it": "\nChange `SUM(col)` to `MAX(col)` or `AVERAGE(col)` in the example. Compare the shape with\n`=BYROW({1,2;3,4},LAMBDA(row,SUM(row)))`.\n\n\n", "version-differences": "\nMicrosoft lists BYCOL for Microsoft 365 and Excel 2024 on Windows and Mac. Build observations\nbelow cover direct errors. Other differences between named builds have not been characterized here.\n\n\n", "what-it-does": "\n`BYCOL(array, lambda)` applies a one-parameter lambda to each entire column and returns one\nresult per column in a single row. An input with `r` rows and `c` columns therefore produces\none row with `c` results when every invocation returns one value.\n\n`=BYCOL({1,2;3,4},LAMBDA(col,SUM(col)))` returns the row `{4,6}`. Each invocation sees a column,\nnot one cell at a time.\n\n\n" }, "signature": { "display": "BYCOL(array, lambda)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "lambda", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "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": "One result per column, from a LAMBDA called on each column", "short_source": "dna-calc-own" }, "docs": { "english_description": "Applies a LAMBDA to each column and returns an array of the results", "microsoft_url": "https://support.microsoft.com/en-us/office/bycol-function-58463999-7de5-49ce-8f38-b7f7a2192bfb" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "BYCOL" }, { "locale": "bg-BG", "name": "BYCOL" }, { "locale": "cs-CZ", "name": "BYCOL" }, { "locale": "da-DK", "name": "BYCOL" }, { "locale": "de-DE", "name": "BYCOL" }, { "locale": "el-GR", "name": "BYCOL" }, { "locale": "en-AU", "name": "BYCOL" }, { "locale": "en-GB", "name": "BYCOL" }, { "locale": "en-US", "name": "BYCOL" }, { "locale": "es-ES", "name": "BYCOL" }, { "locale": "et-EE", "name": "BYCOL" }, { "locale": "fi-FI", "name": "BYCOL" }, { "locale": "fr-FR", "name": "BYCOL*" }, { "locale": "he-IL", "name": "BYCOL" }, { "locale": "hr-HR", "name": "BYCOL" }, { "locale": "hu-HU", "name": "BYCOL" }, { "locale": "id-ID", "name": "BYCOL" }, { "locale": "it-IT", "name": "BYCOL" }, { "locale": "ja-JP", "name": "BYCOL" }, { "locale": "ko-KR", "name": "BYCOL" }, { "locale": "lt-LT", "name": "BYCOL" }, { "locale": "lv-LV", "name": "BYCOL" }, { "locale": "nb-NO", "name": "BYCOL" }, { "locale": "nl-NL", "name": "BYCOL" }, { "locale": "pl-PL", "name": "BYCOL" }, { "locale": "pt-BR", "name": "BYCOL" }, { "locale": "pt-PT", "name": "BYCOL" }, { "locale": "ro-RO", "name": "BYCOL" }, { "locale": "ru-RU", "name": "BYCOL" }, { "locale": "sk-SK", "name": "BYCOL" }, { "locale": "sl-SI", "name": "BYCOL" }, { "locale": "sr-Latn-RS", "name": "BYCOL" }, { "locale": "sv-SE", "name": "BYCOL" }, { "locale": "th-TH", "name": "BYCOL" }, { "locale": "tr-TR", "name": "BYCOL" }, { "locale": "uk-UA", "name": "BYCOL" }, { "locale": "vi-VN", "name": "BYCOL" }, { "locale": "zh-CN", "name": "BYCOL" }, { "locale": "zh-HK", "name": "BYCOL" }, { "locale": "zh-TW", "name": "BYCOL" } ], "signature": { "display": "BYCOL(array, lambda)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "lambda", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "BYCOL", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/bycol-function-58463999-7de5-49ce-8f38-b7f7a2192bfb" }, "try_it": { "formula": "=BYCOL({1,2;3,4},LAMBDA(c,SUM(c)))" }, "url": "https://handbook.dnacalc.com/functions/BYCOL.html", "variants": [], "versions": [] }