{ "category": "Lookup and reference functions", "display_name": "CHOOSEROWS", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.CHOOSEROWS", "implementation_state": { "answer_bank": null, "detail": "Recorded: 16 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 16 recorded answers", "workbook_corpus": { "cells": 16, "matched": 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/arrays.rs#L660-L662", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/dynamic_array_reshape_family.rs#L317-L338" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/arrays::source_error", "catalogue/arrays::prepared", "catalogue/arrays::prepared_one", "catalogue/arrays::result", "catalogue/arrays::choose", "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::parse_integer", "ported/dynamic_array_reshape_family::resolve_selector", "ported/dynamic_array_reshape_family::build_array", "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#L660-L662", "state": "matches", "suite": null, "summary": "Matches all 16 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.CHOOSEROWS.json", "name": "CHOOSEROWS", "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- **`CHOOSECOLS`** is the identical operation on the column axis. Anything established for one\n should be probed for the other rather than assumed, but the pair is symmetric by\n construction and shares an implementation module.\n- **`TAKE` / `DROP`** handle contiguous edge selections — \"first 5 rows\", \"all but the last 2\" —\n without enumerating indices, and express intent better when the selection is contiguous.\n- **`FILTER`** selects rows by predicate and preserves their original order. Use it when the\n criterion is a condition; use `CHOOSEROWS` when the criterion is a position.\n- **`SORT` / `SORTBY`** also produce a permutation of rows, but derive it from the data rather\n than from an explicit index list. `SORTBY` with a computed key and `CHOOSEROWS` with a\n computed index list are two routes to the same reordering.\n- **`INDEX` with `column_num` = 0** returns an entire row and is the pre-dynamic-array idiom\n `CHOOSEROWS` supersedes for multi-row selection.\n- **`VSTACK`** is the joining counterpart: `CHOOSEROWS` takes rows out, `VSTACK` puts rows\n together.\n- **`CHOOSE`** shares only a prefix. It selects among arguments, not among rows.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **Do not normalize the index list.** Sorting or deduplicating it changes the result. The\n common case (distinct ascending indices) hides the bug completely.\n- **Three index branches, not two**: positive, negative, and zero-is-an-error. Negative indices\n must be resolved against the input height before the bounds check.\n- **Row selection is a gather, not a slice.** Implementations that assume contiguity — because\n the common calls are contiguous — will pass their tests and fail on `CHOOSEROWS(A, 3, 1)`.\n- **The module is shared** with the rest of the dynamic-array reshapers\n (`dynamic_array_reshape_family.rs`), so bounds-and-shape logic is common code; a fix here is a\n fix for the siblings, and a regression here is a regression for them.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturn kind: `Array`, of shape (number of index values) × (columns of `array`). It spills;\nspilling itself is host-side adaptation, described in\n[the call pipeline](../model/03-call-pipeline.md).\n\n- **References are resolved first.** `array` is prepared under `ValuesOnlyPreAdapter`, so the\n result is values, not a reference into the original range. Nothing downstream can treat the\n result as a range.\n- **No coercion of selected elements.** Text stays text, logicals stay logicals.\n- **A single-row `array`** admits only index 1 (or `-1`); everything else is out of range.\n\n\n\n### Errors\n\n\nMicrosoft's page documents the failure directly: `CHOOSEROWS` returns `#VALUE!` if any `row_num`\nargument is zero or exceeds the number of rows in `array`; the same bound applies on the\nnegative side by the symmetry of the documented indexing.\n\nAn error value supplied as an argument — as opposed to sitting inside `array` — propagates under\nthe universal coercion rule in\n[coercion and lifting](../model/02-coercion-and-lifting.md).\n\nWhether a fractional index truncates or errors is not established here.\n\n\n", "sources": "\n- Microsoft, CHOOSEROWS function —\n \n (row selection semantics, negative indexing from the end, and the `#VALUE!` condition for zero\n or out-of-range indices).\n- Handbook `content/model/02-coercion-and-lifting.md` (error propagation at the argument\n boundary).\n- Handbook `content/model/03-call-pipeline.md` (`ValuesOnlyPreAdapter`; host-side spill\n adaptation).\n- Handbook `data/functions/FUNC.CHOOSEROWS.json` and `data/presence/FUNC.CHOOSEROWS.json`\n (arity, classification axes, the shared reshape-family 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`CHOOSEROWS(array, row_num1, [row_num2], …)` builds a new array from the rows of `array` named\nby the index arguments, **in the order the indices are given**. Column count is invariant; only\nthe row axis is touched.\n\nBecause the output is driven by the index list rather than by a range, the function does three\njobs at once:\n\n1. **selection** — keep the rows you name, drop the rest;\n2. **reordering** — `CHOOSEROWS(A, 3, 1, 2)` permutes;\n3. **repetition** — an index may appear more than once, and the output row count is the number\n of indices, not the number of distinct indices.\n\nIndices are one-based. Microsoft documents that a **negative index counts from the end**: `-1`\nis the last row. There is no zero index.\n\nThe everyday uses follow directly: `CHOOSEROWS(A, 1)` takes a header row, `CHOOSEROWS(A, -1)`\ntakes the last record, and `CHOOSEROWS(A, SEQUENCE(…))` takes a computed sample — the last of\nwhich depends on how the function treats an array-valued index argument, which is the open\nquestion flagged below.\n\n\n\n### Arguments\n\n\n| Argument | Meaning |\n|---|---|\n| `array` | The array or range whose rows are selected. Required. |\n| `row_num1` | The first row to return. One-based; negative counts from the last row. Required. |\n| `row_num2`, … | Further rows, in output order. Optional, to the arity ceiling of 255 arguments. |\n\nThe argument position most often misjudged is the index list's *ordering* semantics: readers\nreach for `CHOOSEROWS` expecting a filter (which preserves original order) and get a permutation\n(which does not). If you want \"the rows where a condition holds, in their original order\",\n`FILTER` is the function; `CHOOSEROWS` gives you exactly the order you asked for, including an\norder you did not mean to ask for.\n\n\n" }, "signature": { "display": "CHOOSEROWS(array, row_num1, [row_num2], ...)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "row_num1", "optional": false, "repeats": false }, { "description": null, "name": "row_num2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 255, "min": 2 }, "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": "Selected rows of an array, in the order asked for", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns the specified rows from an array", "microsoft_url": "https://support.microsoft.com/en-us/office/chooserows-function-51ace882-9bab-4a44-9625-7274ef7507a3" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "CHOOSEROWS" }, { "locale": "bg-BG", "name": "CHOOSEROWS" }, { "locale": "cs-CZ", "name": "ZVOLITŘÁDKY" }, { "locale": "da-DK", "name": "VÆLGRÆKKER" }, { "locale": "de-DE", "name": "CHOOSEROWS" }, { "locale": "el-GR", "name": "CHOOSEROWS" }, { "locale": "en-AU", "name": "CHOOSEROWS" }, { "locale": "en-GB", "name": "CHOOSEROWS" }, { "locale": "en-US", "name": "CHOOSEROWS" }, { "locale": "es-ES", "name": "ELEGIRFILAS" }, { "locale": "et-EE", "name": "CHOOSEROWS" }, { "locale": "fi-FI", "name": "CHOOSEROWS" }, { "locale": "fr-FR", "name": "CHOISIRLIGNES*" }, { "locale": "he-IL", "name": "CHOOSEROWS" }, { "locale": "hr-HR", "name": "CHOOSEROWS" }, { "locale": "hu-HU", "name": "SORVÁLASZTÁS" }, { "locale": "id-ID", "name": "CHOOSEROWS" }, { "locale": "it-IT", "name": "CHOOSEROWS" }, { "locale": "ja-JP", "name": "CHOOSEROWS" }, { "locale": "ko-KR", "name": "CHOOSEROWS" }, { "locale": "lt-LT", "name": "CHOOSEROWS" }, { "locale": "lv-LV", "name": "CHOOSEROWS" }, { "locale": "nb-NO", "name": "VELGRADER" }, { "locale": "nl-NL", "name": "KIES.RIJEN" }, { "locale": "pl-PL", "name": "WYBIERZ.WIERSZE" }, { "locale": "pt-BR", "name": "CHOOSEROWS" }, { "locale": "pt-PT", "name": "ESCOLHERLINS" }, { "locale": "ro-RO", "name": "CHOOSEROWS" }, { "locale": "ru-RU", "name": "ВЫБОРСТРОК" }, { "locale": "sk-SK", "name": "CHOOSEROWS" }, { "locale": "sl-SI", "name": "CHOOSEROWS" }, { "locale": "sr-Latn-RS", "name": "CHOOSEROWS" }, { "locale": "sv-SE", "name": "VÄLJRADER" }, { "locale": "th-TH", "name": "CHOOSEROWS" }, { "locale": "tr-TR", "name": "SATIRSEÇ" }, { "locale": "uk-UA", "name": "CHOOSEROWS" }, { "locale": "vi-VN", "name": "CHOOSEROWS" }, { "locale": "zh-CN", "name": "CHOOSEROWS" }, { "locale": "zh-HK", "name": "CHOOSEROWS" }, { "locale": "zh-TW", "name": "CHOOSEROWS" } ], "signature": { "display": "CHOOSEROWS(array, row_num1, [row_num2], ...)", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "row_num1", "optional": false, "repeats": false }, { "description": null, "name": "row_num2", "optional": true, "repeats": true } ], "trailing_repeats": true }, "surface_name": "CHOOSEROWS", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/chooserows-function-51ace882-9bab-4a44-9625-7274ef7507a3" }, "try_it": { "formula": "=CHOOSEROWS({1,2;3,4},2)" }, "url": "https://handbook.dnacalc.com/functions/CHOOSEROWS.html", "variants": [], "versions": [] }