{ "category": "Lookup and reference functions", "display_name": "COLUMNS", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.COLUMNS", "implementation_state": { "answer_bank": null, "detail": "Of 932 recorded answers (932 workbook cells), 22 do not match: 6 differ in kind or value, 16 are refused.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "differs", "state_label": "Known larger differences", "summary": "Known larger differences on 22 of 932 recorded answers", "workbook_corpus": { "cells": 933, "matched": 910, "other_mismatch": 6, "pending": 1, "refused": 16 } }, "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#L225-L231", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L1821-L1828" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/lookup::eager", "catalogue/lookup::pattern", "catalogue/lookup::matches", "catalogue/lookup::Line::len", "catalogue/lookup::Line::scan", "catalogue/lookup::reader", "catalogue/lookup::cell_value", "catalogue/lookup::rows", "catalogue/lookup::columns", "catalogue/lookup::value", "catalogue/lookup::span", "catalogue/lookup::shape", "catalogue/lookup::index_number", "catalogue/lookup::index", "catalogue/lookup::selector", "catalogue/lookup::indexed", "catalogue/lookup::select", "catalogue/lookup::row", "catalogue/lookup::column", "catalogue/lookup::position_of", "catalogue/lookup::extent", "catalogue/lookup::areas" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L225-L231", "state": "differs", "suite": null, "summary": "Known larger differences on 22 of 932 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.COLUMNS.json", "name": "COLUMNS", "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\n- **`ROWS`** is the same measurement on the other axis. Together they give an array's shape.\n- **`COLUMN`** locates rather than counts, and the name similarity is the standing trap.\n- **`AREAS`** counts the rectangles in a reference where `COLUMNS` measures extent. For a\n multi-area reference the two questions come apart, which is why `AREAS` exists.\n- **`INDEX`, `OFFSET`, `TAKE`, `DROP`, `WRAPROWS`** all take width or height arguments that are\n frequently computed with `COLUMNS`.\n- **`HLOOKUP`'s `row_index_num`** and **`VLOOKUP`'s `col_index_num`** are commonly written as\n `COLUMNS($A$1:B$1)` or similar so that the index advances as the formula is copied — one of\n the oldest idioms in spreadsheet practice, and one that `XLOOKUP` removes the need for.\n- **`SEQUENCE(1, COLUMNS(a))`** is the modern way to build an index vector matching an array's\n width.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- **Answer from the reference, not from the values.** Materializing a whole-column reference to\n count its columns is correct and catastrophic. The `RefsVisibleInAdapter` preparation profile\n exists so this function can avoid exactly that.\n- **The multi-area case needs a declared policy**, because there is no single right answer. An\n implementation must choose and record its choice rather than fall out of whatever its\n reference representation happens to make easy.\n- **1×1 arrays.** The pipeline's argument preparation collapses a single-cell reference to a\n scalar for values-only functions, but `COLUMNS` is not values-only, and the unit-array\n preservation caveat described in [the call pipeline](../model/03-call-pipeline.md) is exactly\n the sort of normalization that can silently change a shape query's answer.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturn kind: `Number` — a positive integer.\n\n- **No coercion of contents.** Element kinds are irrelevant. An array of errors has a width.\n- **Nothing is scanned.** Unlike `COUNT`-style functions, `COLUMNS` does not visit elements, so\n an error inside the range does not become the result. This is the practical difference between\n a shape query and an aggregate: see the scan-policy discussion in\n [coercion and lifting](../model/02-coercion-and-lifting.md).\n- **A spill anchor** (`B1#`) has a width that changes when the spill changes; `COLUMNS(B1#)` is\n the idiomatic way to ask how wide a dynamic result currently is, and its dependency behaviour\n is a property of the spill-anchor reference shape rather than of this function.\n- **A structured reference** to several table columns has a width that tracks the table.\n\n\n\n### Errors\n\n\nMicrosoft's page does not publish an error table for `COLUMNS`. The expected failure is an\nargument that is neither an array nor a reference, for which `#VALUE!` is this family's\nconventional code — recorded here as expected, not verified. An error value passed as the\nargument propagates under the universal rule in\n[coercion and lifting](../model/02-coercion-and-lifting.md); note that this is different from an\nerror *inside* the array, which does not affect the count.\n\n\n", "sources": "\n- Microsoft, COLUMNS function —\n \n (argument definition: an array, an array formula, or a reference to a range of cells).\n- Handbook `content/model/01-value-universe.md` (array kind; reference shapes).\n- Handbook `content/model/02-coercion-and-lifting.md` (shape queries versus scans; error\n propagation).\n- Handbook `content/model/03-call-pipeline.md` (`RefsVisibleInAdapter`; unit-array\n preservation).\n- Handbook `data/functions/FUNC.COLUMNS.json` and `data/presence/FUNC.COLUMNS.json` (arity,\n classification axes, implementing 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`COLUMNS(array)` returns the number of columns in an array or reference. It is a measurement of\nshape, not of content: no cell is read, no value is coerced, and empty cells inside the range\ncount exactly as much as filled ones.\n\nThe distinction worth stating at the top, because the names invite the mistake: `COLUMNS` counts\ncolumns, `COLUMN` locates one. `COLUMNS(C1:E1)` is 3; `COLUMN(C1:E1)` is the array 3, 4, 5.\n\n\n### Arguments\n\n\n| Argument | Meaning |\n|---|---|\n| `array` | An array, an array formula's result, or a reference to a range of cells. Required, exactly one. |\n\nMicrosoft's page names this argument `array` and describes it as an array, an array formula, or\na reference to a range of cells. Two consequences readers trip over:\n\n- **A single cell is a 1×1 shape**, so `COLUMNS(A1)` is 1 rather than an error.\n- **A multi-area reference** — `COLUMNS((A1:B2,D1:E2))` — has no single width. What `COLUMNS`\n reports for a union is not established here, and it is not obvious: the plausible answers\n (the first area's width, the bounding box's width, an error) are all defensible.\n\nWhat `COLUMNS` does with a bare scalar that is neither array nor reference is likewise not\nestablished here.\n\n\n" }, "signature": { "display": "COLUMNS(array)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 1, "min": 1 }, "category": "Lookup and reference functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "RefOnly", "host_interaction_class": "WorkbookState", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "HostSerialized", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "How many columns an array or reference has", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the number of columns in a reference", "microsoft_url": "https://support.microsoft.com/en-us/office/columns-function-4e8e7b4e-e603-43e8-b177-956088fa48ca" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "COLUMNS" }, { "locale": "bg-BG", "name": "COLUMNS" }, { "locale": "cs-CZ", "name": "SLOUPCE" }, { "locale": "da-DK", "name": "KOLONNER" }, { "locale": "de-DE", "name": "SPALTEN" }, { "locale": "el-GR", "name": "COLUMNS" }, { "locale": "en-AU", "name": "COLUMNS" }, { "locale": "en-GB", "name": "COLUMNS" }, { "locale": "en-US", "name": "COLUMNS" }, { "locale": "es-ES", "name": "COLUMNS" }, { "locale": "et-EE", "name": "COLUMNS" }, { "locale": "fi-FI", "name": "SARAKKEET" }, { "locale": "fr-FR", "name": "COLONNES" }, { "locale": "he-IL", "name": "COLUMNS" }, { "locale": "hr-HR", "name": "COLUMNS" }, { "locale": "hu-HU", "name": "OSZLOPOK" }, { "locale": "id-ID", "name": "COLUMNS" }, { "locale": "it-IT", "name": "COLUMNS" }, { "locale": "ja-JP", "name": "列" }, { "locale": "ko-KR", "name": "열" }, { "locale": "lt-LT", "name": "COLUMNS" }, { "locale": "lv-LV", "name": "COLUMNS" }, { "locale": "nb-NO", "name": "KOLONNER" }, { "locale": "nl-NL", "name": "KOLOMMEN" }, { "locale": "pl-PL", "name": "LICZBA.KOLUMN" }, { "locale": "pt-BR", "name": "COLUNAS" }, { "locale": "pt-PT", "name": "COLS" }, { "locale": "ro-RO", "name": "COLUMNS" }, { "locale": "ru-RU", "name": "ЧИСЛСТОЛБ" }, { "locale": "sk-SK", "name": "COLUMNS" }, { "locale": "sl-SI", "name": "COLUMNS" }, { "locale": "sr-Latn-RS", "name": "KOLONE" }, { "locale": "sv-SE", "name": "KOLUMNER" }, { "locale": "th-TH", "name": "COLUMNS" }, { "locale": "tr-TR", "name": "SÜTUNSAY" }, { "locale": "uk-UA", "name": "COLUMNS" }, { "locale": "vi-VN", "name": "COLUMNS" }, { "locale": "zh-CN", "name": "列" }, { "locale": "zh-HK", "name": "COLUMNS" }, { "locale": "zh-TW", "name": "COLUMNS" } ], "signature": { "display": "COLUMNS(array)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "COLUMNS", "version_marker": null, "xlcall": { "code": "77", "symbol": "xlfColumns" } }, "microsoft": "https://support.microsoft.com/en-us/office/columns-function-4e8e7b4e-e603-43e8-b177-956088fa48ca" }, "try_it": { "formula": "=COLUMNS(B2:C4)", "inputs": { "B2": 1, "B3": 2, "B4": 3, "C2": 10, "C3": 20, "C4": 30 } }, "url": "https://handbook.dnacalc.com/functions/COLUMNS.html", "variants": [], "versions": [] }