{ "category": "Information functions", "display_name": "CELL", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CELL", "implementation_state": { "answer_bank": null, "detail": "Recorded: 771 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 771 recorded answers", "workbook_corpus": { "cells": 773, "matched": 771, "pending": 2 } }, "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/host_facts.rs#L447-L447" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/host_facts::first_cell", "catalogue/host_facts::cell_value", "catalogue/host_facts::column_letters", "catalogue/host_facts::facts", "catalogue/host_facts::qualified_sheet", "catalogue/host_facts::cell", "catalogue/host_facts::s_number", "catalogue/host_facts::info", "catalogue/host_facts::sheet", "format/cell_info::sections", "format/cell_info::tokens", "format/cell_info::is_date_time", "format/cell_info::date_time_class", "format/cell_info::places", "format/cell_info::number_class", "format/cell_info::classify", "ported/a1_refs::split_prefix", "ported/a1_refs::parse_cell_token", "ported/a1_refs::parse_column_token", "ported/a1_refs::parse_row_token", "ported/a1_refs::parse_a1_reference", "ported/address::address_name_character", "ported/address::address_name_is_reference", "ported/address::quote_sheet_text_if_needed" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/host_facts.rs#L447-L447", "state": "matches", "suite": null, "summary": "Matches all 771 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CELL.json", "name": "CELL", "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- **`INFO`** is `CELL`'s sibling: same category, same host dependence, same \"cannot be evaluated\n without Excel\" property, but asking about the environment rather than about a cell.\n- **`TYPE`** and **`CELL(\"type\", …)`** are not the same function and do not return the same\n alphabet. `TYPE` returns a numeric kind code for a *value*; `CELL(\"type\", …)` returns a\n one-letter classification of a *cell*. If you want to know what kind of value you have, use\n `TYPE`.\n- **`ROW` and `COLUMN`** give the same numbers as `CELL(\"row\", …)` and `CELL(\"col\", …)`, without\n the host-query machinery, and are the better choice.\n- **`ADDRESS`** builds an address from coordinates; `CELL(\"address\", …)` reads one from a\n reference. They meet in the middle.\n- **`SHEET` and `SHEETS`** answer the sheet-level questions `CELL` does not.\n- **`ISFORMULA` and `FORMULATEXT`** answer the formula questions `CELL(\"contents\")` and\n `CELL(\"type\")` cannot.\n- **`CELL(\"filename\", …)`** is the traditional route to the workbook or sheet name, usually\n wrapped in `MID`/`FIND`. It is fragile — it depends on the file having been saved and on the\n path's punctuation — and it is the reason many workbooks break when moved.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n1. **`CELL` cannot be implemented in the function layer.** It must be a declared host query with\n a defined failure mode when no host is present. Faking `\"filename\"` or `\"format\"` from local\n state produces answers that look right and are not.\n2. **The reference must survive preparation unresolved.** If the dispatch layer dereferences,\n `\"address\"`, `\"row\"`, `\"col\"` and `\"width\"` all lose their subject.\n3. **The omitted-`reference` path is a different query**, against application state (last changed\n cell), not against an argument. It should be modelled as such, and its non-determinism\n documented rather than smoothed over.\n4. **`\"width\"` returns an array of two.** A scalar-shaped return path will silently drop half the\n answer.\n5. **`\"format\"` and `\"prefix\"` are locale- and version-scoped.** Any claim about their outputs\n must name the build and locale, per the Handbook's claim rules.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nThe return kind depends on `info_type`: `Text` for `\"address\"`, `\"filename\"`, `\"format\"`,\n`\"prefix\"` and `\"type\"`; `Number` for `\"col\"`, `\"row\"`, `\"color\"`, `\"parentheses\"` and\n`\"protect\"`; whatever the cell holds for `\"contents\"`; and an **array of two items** for\n`\"width\"` — the only `info_type` whose result is not a scalar, and a shape that will spill or be\nintersected depending on context.\n\n- **A multi-cell reference is reduced.** `\"address\"` reports the first cell, `\"contents\"` the\n upper-left. `CELL` does not aggregate.\n- **`\"contents\"` returns the value, never the formula.** `FORMULATEXT` is the function for the\n formula text.\n- **`\"filename\"` on an unsaved workbook** has a documented-empty answer in the folklore and no\n observation in this Handbook.\n- **`\"type\"` is coarse.** It reports a one-letter classification of the cell's content, not the\n fine-grained kind that `TYPE` returns. The two functions have similar names and different\n jobs; see \"Relationships\".\n- **`\"format\"` is locale- and version-sensitive.** The text codes describe number formats, and\n which code a given format maps to is a per-build fact this Handbook has not recorded.\n- **Volatility.** With `reference` supplied the function is still declared\n `VolatileContextual` — the properties it reads (format, width, protection) can change without\n any formula input changing, and Excel's dependency graph does not track formatting edits the\n way it tracks values. A `CELL(\"format\", A1)` result can therefore be stale after a formatting\n change until a recalculation happens.\n\n\n\n### Errors\n\n\nMicrosoft's page is the documentation of record; the Handbook has read its `info_type` table and\nits reference-argument caveat, and does not have a documented error table for this function to\nreproduce.\n\n- an unrecognised `info_type` — `#VALUE!`\n- a `reference` argument that is not a reference — `#VALUE!`\n- an arity failure (zero arguments, or three) — `#VALUE!`\n- no host available — the call is refused rather than answered\n\n`#REF!` from a deleted target and `#NAME?` from an unresolvable name would arise before `CELL`\nruns, in reference resolution ([coercion and lifting](../model/02-coercion-and-lifting.md)).\n\n\n", "sources": "- Microsoft, \"CELL function\" —\n .\n Read for this page: the full `info_type` table verbatim, and the reference-argument caveat\n (\"Although technically reference is optional, including it in your formula is encouraged…\")\n together with the documented consequences of omitting it.\n- Handbook, [the call pipeline](../model/03-call-pipeline.md) — `RefsVisibleInAdapter`,\n caller-aware functions, and host-side adaptation as an engine obligation.\n- Handbook, [the execution context](../model/04-execution-context.md) — the calling-cell and\n workbook state a host query reads.\n- Handbook, [coercion and lifting](../model/02-coercion-and-lifting.md) — reference resolution\n as an explicit step with its own failure modes.\n- Handbook, [claim language and honesty](../model/06-claim-language.md) — why a build- and\n locale-scoped result cannot be published without its axes.\n\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`CELL(info_type, [reference])` returns one property of a cell, selected by name.\n\nMicrosoft's published `info_type` table, verbatim:\n\n| `info_type` | Returns |\n|---|---|\n| `\"address\"` | Reference of the first cell in reference, as text. |\n| `\"col\"` | Column number of the cell in reference. |\n| `\"color\"` | The value 1 if the cell is formatted in color for negative values; otherwise returns 0 (zero). |\n| `\"contents\"` | Value of the upper-left cell in reference; not a formula. |\n| `\"filename\"` | Filename (including full path) of the file that contains reference, as text. |\n| `\"format\"` | Text value corresponding to the number format of the cell. |\n| `\"parentheses\"` | The value 1 if the cell is formatted with parentheses for positive or all values; otherwise returns 0. |\n| `\"prefix\"` | Text value corresponding to the \"label prefix\" of the cell. |\n| `\"protect\"` | The value 0 if the cell is not locked; otherwise returns 1 if the cell is locked. |\n| `\"row\"` | Row number of the cell in reference. |\n| `\"type\"` | Text value corresponding to the type of data in the cell. |\n| `\"width\"` | Returns an array with 2 items. |\n\nSeveral of these — `\"color\"`, `\"parentheses\"`, `\"prefix\"`, and much of `\"format\"` — are\nsurvivals from Lotus 1-2-3 compatibility and from Excel's macro-sheet era. They still answer,\nbut they describe a formatting world that modern workbooks mostly do not use.\n\n\n\n### Arguments\n\n\n**`info_type`** — required. Text naming the property. It is coerced to text and matched\ncase-insensitively after trimming, so `\"ROW\"`, `\"row\"` and `\" Row \"` are the same request. A\nname outside the twelve is a failure, not a null result.\n\n**`reference`** — optional, and this is the argument position most commonly misunderstood.\nMicrosoft's own caveat is worth quoting because it is unusually blunt for a reference page:\n\"Although technically reference is optional, including it in your formula is encouraged, unless\nyou understand the effect its absence has on your formula result.\"\n\nWhat its absence does: `CELL` falls back to the **last cell that was changed**, which is a piece\nof application state, not a property of the formula. The documented consequences are that\ncalculation timing varies by platform, that co-authoring can report the wrong active cell, and\nthat a plain recalculation (F9) can produce a new result with no edit anywhere. That is why the\nfunction's declared volatility is `VolatileContextual` and its thread-safety class is\n`HostSerialized`: an argument-free `CELL` is a formula whose answer depends on what the user did\nlast.\n\nSupply the reference. There is no case in which omitting it makes a formula more correct.\n\nNote also that `reference` is a **reference position, not a value position**: the live reference\nsurvives argument preparation, which is what lets `\"address\"` and `\"row\"` mean anything. Handing\n`CELL` a computed value where a reference is expected is a failure, not a coercion.\n\n\n" }, "signature": { "display": "CELL(info_type, [reference])", "parameters": [ { "description": null, "name": "info_type", "optional": false, "repeats": false }, { "description": null, "name": "reference", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 2, "min": 1 }, "category": "Information functions", "classification": { "arg_preparation_profile": "RefsVisibleInAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "CallerContext", "host_interaction_class": "WorkbookState", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "CallerContext", "thread_safety_class": "HostSerialized", "volatility_class": "VolatileContextual" }, "descriptions": { "long": null, "short": "A fact about a cell, such as its address, format, contents or width", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns information about the formatting, location, or contents of a cell", "microsoft_url": "https://support.microsoft.com/en-us/office/cell-function-51bd39a5-f338-4dbe-a33f-955d67c2b2cf" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CELL" }, { "locale": "bg-BG", "name": "CELL" }, { "locale": "cs-CZ", "name": "POLÍČKO" }, { "locale": "da-DK", "name": "CELLE" }, { "locale": "de-DE", "name": "ZELLE" }, { "locale": "el-GR", "name": "CELL" }, { "locale": "en-AU", "name": "CELL" }, { "locale": "en-GB", "name": "CELL" }, { "locale": "en-US", "name": "CELL" }, { "locale": "es-ES", "name": "CELDA" }, { "locale": "et-EE", "name": "CELL" }, { "locale": "fi-FI", "name": "SOLU" }, { "locale": "fr-FR", "name": "CELLULE" }, { "locale": "he-IL", "name": "CELL" }, { "locale": "hr-HR", "name": "CELL" }, { "locale": "hu-HU", "name": "CELLA" }, { "locale": "id-ID", "name": "CELL" }, { "locale": "it-IT", "name": "CELLA" }, { "locale": "ja-JP", "name": "CELL" }, { "locale": "ko-KR", "name": "CELL" }, { "locale": "lt-LT", "name": "CELL" }, { "locale": "lv-LV", "name": "CELL" }, { "locale": "nb-NO", "name": "CELLE" }, { "locale": "nl-NL", "name": "CEL" }, { "locale": "pl-PL", "name": "KOMÓRKA" }, { "locale": "pt-BR", "name": "CÉLULA" }, { "locale": "pt-PT", "name": "CÉL" }, { "locale": "ro-RO", "name": "CELL" }, { "locale": "ru-RU", "name": "ЯЧЕЙКА" }, { "locale": "sk-SK", "name": "CELL" }, { "locale": "sl-SI", "name": "CELL" }, { "locale": "sr-Latn-RS", "name": "CELL" }, { "locale": "sv-SE", "name": "CELL" }, { "locale": "th-TH", "name": "CELL" }, { "locale": "tr-TR", "name": "HÜCRE" }, { "locale": "uk-UA", "name": "CELL" }, { "locale": "vi-VN", "name": "CELL" }, { "locale": "zh-CN", "name": "CELL" }, { "locale": "zh-HK", "name": "CELL" }, { "locale": "zh-TW", "name": "CELL" } ], "signature": { "display": "CELL(info_type, [reference])", "parameters": [ { "description": null, "name": "info_type", "optional": false, "repeats": false }, { "description": null, "name": "reference", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "CELL", "version_marker": null, "xlcall": { "code": "125", "symbol": "xlfCell" } }, "microsoft": "https://support.microsoft.com/en-us/office/cell-function-51bd39a5-f338-4dbe-a33f-955d67c2b2cf" }, "try_it": { "formula": "=CELL(\"contents\",B2)", "inputs": { "B2": 1 } }, "url": "https://handbook.dnacalc.com/functions/CELL.html", "variants": [], "versions": [] }