{
  "category": "Lookup and reference functions",
  "display_name": "ROW",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.ROW",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 11 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 11 recorded answers",
    "workbook_corpus": {
      "cells": 12,
      "matched": 11,
      "pending": 1
    }
  },
  "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#L204-L210"
      ],
      "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::areas"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/lookup.rs#L204-L210",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 11 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.ROW.json",
  "name": "ROW",
  "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- **`COLUMN`** is the exact transpose: same two forms, same caller-aware behaviour, horizontal\n  array instead of vertical.\n- **`ROWS`** answers the adjacent question — *how many* rows, rather than *which* — and always\n  returns a scalar. Confusing the two is the single most common mistake here:\n  `ROW(A5:A8)` is `{5;6;7;8}`; `ROWS(A5:A8)` is `4`.\n- **`SEQUENCE`** replaces the `ROW(INDIRECT(...))` idiom for generating `1..n`, without\n  volatility and without abusing a coordinate function as a generator.\n- **`CELL(\"row\", ref)`** is another route to the same number, through a different and much\n  broader function.\n- **`OFFSET`, `INDEX`, `INDIRECT`, `ADDRESS`** are the rest of the reference family; `ROW` is\n  a reference *reader*.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n\n- The two forms are different functions sharing a name. The no-argument form needs the caller's\n  address from the evaluation context; the one-argument form needs no context at all. An engine\n  that supplies caller context only when an argument is absent has to keep that seam explicit.\n- The area form returns an array whose length is the reference's row span — including for\n  whole-column references. Materializing that eagerly is a performance decision with visible\n  consequences; refusing to materialize it changes the semantics.\n- `ROW` must not dereference. Its answer is a property of the address, and a cell's contents —\n  including whether it is blank — is irrelevant.\n- The result of the area form is a *column* array. Getting the orientation wrong is invisible\n  in a 1×1 case and wrong everywhere else.\n- Caller-aware functions interact with anything that evaluates a formula away from a cell:\n  defined names, array contexts, and add-in entry points each need a decided answer.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nThe return kind is a number for the no-argument and single-cell forms, and a vertical array of\nnumbers for a multi-row area.\n\n- **Multi-area references** (`ROW((A1:A2,C1:C2))`) are not described by the documentation and\n  the Handbook has not verified their behaviour.\n- **What `ROW()` means outside a cell** — in a defined name, in a conditional-format rule, in\n  an add-in call — depends on the evaluation context the host supplies, and is host behaviour\n  rather than function semantics.\n\n\n\n### Errors\n\n- an argument that is not a reference, refused at entry rather than returning an error value;\n- `#REF!` propagating from a reference that has been invalidated (deleted rows), which is\n  reference resolution failing before `ROW` runs;\n- `#SPILL!` at publication for an array result that cannot be placed — a host outcome, not a\n  `ROW` outcome.\n\n\n",
    "sources": "- Microsoft, *ROW function* —\n  <https://support.microsoft.com/en-us/office/row-function-3a63b74a-c4d0-4093-b49a-e76eb49a6d8d>\n  (syntax, the optional reference, and the caller-row behaviour when it is omitted). Not\n  retrieved for this page; the behaviour above is stated as documented behaviour and should be\n  re-checked against the page.\n- Handbook `content/model/01-value-universe.md` (reference shapes, `Missing` versus `Empty`)\n  and `content/model/03-call-pipeline.md` (reference-aware preparation, caller-aware\n  functions).\n- Handbook `data/functions/FUNC.ROW.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`ROW` reports a **row coordinate**, in one of two quite different ways depending on whether it\nis given an argument.\n\n1. **`ROW()`** — no argument — returns the 1-based row index of **the cell containing the\n   formula**. It reads nothing from the sheet's contents; it reads the evaluation context. This\n   makes `ROW()` one of the small set of *caller-aware* functions, alongside `COLUMN()` and\n   `CELL` with an omitted reference. Two identical formulas in two cells return different\n   answers.\n2. **`ROW(reference)`** — returns the 1-based row index of the reference. For a single cell,\n   that is one number. For an area spanning several rows, it is a **vertical array of the row\n   indices from top to bottom**: `ROW(A5:A8)` is `{5;6;7;8}`.\n\nThat second behaviour is the one worth internalizing, because it is the engine behind a large\nfamily of array idioms. `ROW(INDIRECT(\"1:\"&n))` is the classic way to manufacture the sequence\n`1..n` in a pre-`SEQUENCE` Excel, and `ROW(range) - ROW(top_of_range) + 1` is the classic way\nto get positions relative to a range's top. Both are consequences of `ROW` of an area being an\narray rather than a scalar.\n\n\n\n### Arguments\n\n\n**`reference`** — optional. A reference whose row index is wanted.\n\nThree points about this single argument:\n\n- **Omission is meaningful, not a default.** Omitting the argument does not substitute a value;\n  it switches `ROW` into caller-aware mode. This is the `Missing`-versus-`Empty` distinction of\n  [the value universe](../model/01-value-universe.md) doing real work: an omitted argument and\n  an argument that resolves to a blank cell are not the same call.\n- **A multi-row area gives an array, not the top row.** Readers expecting a scalar and getting\n  a spill (or, historically, an implicit intersection) are meeting this rule.\n\n\n"
  },
  "signature": {
    "display": "ROW([reference])",
    "parameters": [
      {
        "description": null,
        "name": "reference",
        "optional": true,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 1,
        "min": 0
      },
      "category": "Lookup and reference 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": "NonVolatile"
      },
      "descriptions": {
        "long": null,
        "short": "Row number of the first cell of a reference (of the formula's cell when left out)",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the row number of a reference",
        "microsoft_url": "https://support.microsoft.com/en-us/office/row-function-3a63b74a-c4d0-4093-b49a-e76eb49a6d8d"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "صف"
        },
        {
          "locale": "bg-BG",
          "name": "ROW"
        },
        {
          "locale": "cs-CZ",
          "name": "ŘÁDEK"
        },
        {
          "locale": "da-DK",
          "name": "RÆKKE"
        },
        {
          "locale": "de-DE",
          "name": "ROW"
        },
        {
          "locale": "el-GR",
          "name": "ROW"
        },
        {
          "locale": "en-AU",
          "name": "ROW"
        },
        {
          "locale": "en-GB",
          "name": "ROW"
        },
        {
          "locale": "en-US",
          "name": "ROW"
        },
        {
          "locale": "es-ES",
          "name": "FILA"
        },
        {
          "locale": "et-EE",
          "name": "ROW"
        },
        {
          "locale": "fi-FI",
          "name": "RIVI"
        },
        {
          "locale": "fr-FR",
          "name": "LIGNE*"
        },
        {
          "locale": "he-IL",
          "name": "ROW"
        },
        {
          "locale": "hr-HR",
          "name": "ROW"
        },
        {
          "locale": "hu-HU",
          "name": "SOR"
        },
        {
          "locale": "id-ID",
          "name": "ROW"
        },
        {
          "locale": "it-IT",
          "name": "ROW"
        },
        {
          "locale": "ja-JP",
          "name": "ROW"
        },
        {
          "locale": "ko-KR",
          "name": "ROW"
        },
        {
          "locale": "lt-LT",
          "name": "ROW"
        },
        {
          "locale": "lv-LV",
          "name": "ROW"
        },
        {
          "locale": "nb-NO",
          "name": "RAD"
        },
        {
          "locale": "nl-NL",
          "name": "RIJ"
        },
        {
          "locale": "pl-PL",
          "name": "WIERSZ"
        },
        {
          "locale": "pt-BR",
          "name": "ROW"
        },
        {
          "locale": "pt-PT",
          "name": "LIN"
        },
        {
          "locale": "ro-RO",
          "name": "ROW"
        },
        {
          "locale": "ru-RU",
          "name": "СТРОКА"
        },
        {
          "locale": "sk-SK",
          "name": "Rnv"
        },
        {
          "locale": "sl-SI",
          "name": "ROW"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "RED"
        },
        {
          "locale": "sv-SE",
          "name": "RAD"
        },
        {
          "locale": "th-TH",
          "name": "ROW"
        },
        {
          "locale": "tr-TR",
          "name": "NORMAL SÜRE VE UZATMA GALİBİYETLERİ"
        },
        {
          "locale": "uk-UA",
          "name": "ROW"
        },
        {
          "locale": "vi-VN",
          "name": "ROW"
        },
        {
          "locale": "zh-CN",
          "name": "ROW"
        },
        {
          "locale": "zh-HK",
          "name": "ROW"
        },
        {
          "locale": "zh-TW",
          "name": "ROW"
        }
      ],
      "signature": {
        "display": "ROW([reference])",
        "parameters": [
          {
            "description": null,
            "name": "reference",
            "optional": true,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "ROW",
      "version_marker": null,
      "xlcall": {
        "code": "8",
        "symbol": "xlfRow"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/row-function-3a63b74a-c4d0-4093-b49a-e76eb49a6d8d"
  },
  "try_it": {
    "formula": "=ROW(B3)",
    "inputs": {
      "B3": 2
    }
  },
  "url": "https://handbook.dnacalc.com/functions/ROW.html",
  "variants": [],
  "versions": []
}