{ "category": "Lookup and reference functions", "display_name": "DROP", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.DROP", "implementation_state": { "answer_bank": null, "detail": "Recorded: 17 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 17 recorded answers", "workbook_corpus": { "cells": 17, "matched": 17 } }, "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#L653-L659", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/dynamic_array_reshape_family.rs#L392-L415" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/arrays::source_error", "catalogue/arrays::prepared", "catalogue/arrays::prepared_one", "catalogue/arrays::result", "catalogue/arrays::run", "catalogue/arrays::sub_area", "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::get", "ported/dynamic_array_reshape_family::parse_integer", "ported/dynamic_array_reshape_family::build_array", "ported/dynamic_array_reshape_family::take_span", "ported/dynamic_array_reshape_family::drop_span", "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#L653-L659", "state": "matches", "suite": null, "summary": "Matches all 17 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.DROP.json", "name": "DROP", "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- **`TAKE`** is the complement: `DROP(a, n)` and `TAKE(a, n)` partition the array's rows. Which\n one reads better depends on whether you are naming what you keep or what you discard.\n- **`CHOOSEROWS` / `CHOOSECOLS`** handle non-contiguous selections. If the selection is\n \"everything except the first row\", `DROP` says it in one argument where `CHOOSEROWS` would\n need an index vector.\n- **`FILTER`** removes rows by predicate rather than by position, and returns `#CALC!` on an\n empty result for the same structural reason — unless its `if_empty` argument is supplied.\n `DROP` has no `if_empty`.\n- **`EXPAND`** is the growing counterpart to this shrinking one.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- **The empty result is the whole design problem.** Every implementation needs a decision point\n where \"the remainder has zero rows or zero columns\" becomes `#CALC!` rather than an\n ill-formed array. Getting this wrong produces an array with a zero dimension that then\n corrupts whatever consumes it, and the failure surfaces far from the cause.\n- **Sign handling before bounds checking.** Convert the signed count into a (start, length) pair\n first, then range-check. Mixing the two produces off-by-ones at exactly `n = height`.\n- **Both axes in one pass.** Trimming rows then columns and trimming columns then rows must give\n the same rectangle — they do, for a rectangular remainder — but an implementation that\n materializes an intermediate array between the two steps doubles its memory traffic on large\n ranges for no benefit.\n- **The lift positions are declared, not incidental.** `by_index_scalar_array_lift(positions=1|2)`\n means the dispatch layer, not the kernel, broadcasts those arguments. An implementation that\n handles arrays inside its own kernel for those positions will diverge from the declared\n pipeline even where the results agree.\n- The module is shared with the rest of the dynamic-array reshapers, so the shape-and-bounds\n discipline is common code.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturn kind: `Array`. The result spills; spilling is host-side adaptation, not function\nsemantics ([the call pipeline](../model/03-call-pipeline.md)).\n\n- **References are resolved first.** `array` is prepared under `ValuesOnlyPreAdapter`, so the\n result carries values, not reference structure.\n- **Dropping everything.** If `rows` is at least the array's height (or `columns` at least its\n width), nothing remains. There is no empty array in the published value model\n ([value universe](../model/01-value-universe.md)), so this case has to become an error rather\n than an empty result — see below.\n- **Fractional counts.** Whether `2.7` truncates or errors is not established here.\n\n\n\n### Errors\n\n\nMicrosoft's page for `DROP` documents `#VALUE!` for an invalid argument and `#CALC!` for the\ncase where the result would be an empty array. `#CALC!` is the calculation engine's \"cannot\nproduce a value\" code, and the empty-array case is one of the two canonical producers of it\nlisted in [the value universe](../model/01-value-universe.md) — the other being the uncalled\nlambda.\n\nThat pairing is the thing to remember about `DROP`: over-dropping does not give you nothing, it\ngives you `#CALC!`. Formulas that compute a drop count from data must either guarantee the count\nis smaller than the extent or wrap the call in `IFERROR`.\n\nAn error value supplied as an argument propagates under the universal rule in\n[coercion and lifting](../model/02-coercion-and-lifting.md).\n\n\n", "sources": "- Microsoft, DROP function —\n \n (the `rows` and `columns` arguments, the negative-from-the-end convention, and the documented\n `#VALUE!` and `#CALC!` conditions).\n- Handbook `content/model/01-value-universe.md` (`#CALC!`; no empty array at the published\n boundary).\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`;\n `ByIndexScalarArrayLift`; host-side spill adaptation).\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`DROP(array, rows, [columns])` removes a contiguous band from the **edge** of an array and\nreturns what is left. The sign of each count chooses the edge:\n\n- `rows` positive — remove that many rows from the **top**;\n- `rows` negative — remove that many rows from the **bottom**;\n- `columns` positive — remove that many columns from the **left**;\n- `columns` negative — remove that many columns from the **right**.\n\nBoth axes are trimmed in the same call when both arguments are given; the result is the\nrectangular remainder. Zero removes nothing on that axis, and omitting `columns` leaves the\ncolumn axis untouched.\n\n`DROP` is the exact complement of `TAKE`: for a non-negative `n`, `TAKE` keeps the band `DROP`\nremoves. Because both use the sign convention for the edge, the pair covers all four\n\"first/last n rows/columns\" operations between them without a mode argument.\n\n\n\n### Arguments\n\n\n| Argument | Meaning |\n|---|---|\n| `array` | The array or range to trim. Required. |\n| `rows` | Number of rows to remove; positive from the top, negative from the bottom. Required. |\n| `columns` | Number of columns to remove; positive from the left, negative from the right. Optional. |\n\nThe argument most often misused is `rows` with the wrong sign: \"drop the last row\" is `-1`, not\n`1`, and the mistake is silent — it returns a plausible array of the right shape from the wrong\nend.\n\n\n" }, "signature": { "display": "DROP(array, rows, [columns])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "rows", "optional": false, "repeats": false }, { "description": null, "name": "columns", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 3, "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": "An array with a number of rows or columns removed from its start or end", "short_source": "dna-calc-own" }, "docs": { "english_description": "Excludes a specified number of rows or columns from the start or end of an array", "microsoft_url": "https://support.microsoft.com/en-us/office/drop-function-1cb4e151-9e17-4838-abe5-9ba48d8c6a34" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "DROP" }, { "locale": "bg-BG", "name": "DROP" }, { "locale": "cs-CZ", "name": "ZAHODIT" }, { "locale": "da-DK", "name": "UDELAD" }, { "locale": "de-DE", "name": "DROP" }, { "locale": "el-GR", "name": "DROP" }, { "locale": "en-AU", "name": "DROP" }, { "locale": "en-GB", "name": "DROP" }, { "locale": "en-US", "name": "DROP" }, { "locale": "es-ES", "name": "EXCLUIR" }, { "locale": "et-EE", "name": "DROP" }, { "locale": "fi-FI", "name": "DROP" }, { "locale": "fr-FR", "name": "EXCLURE*" }, { "locale": "he-IL", "name": "DROP" }, { "locale": "hr-HR", "name": "DROP" }, { "locale": "hu-HU", "name": "ELTÁVOLÍT" }, { "locale": "id-ID", "name": "DROP" }, { "locale": "it-IT", "name": "DROP" }, { "locale": "ja-JP", "name": "DROP" }, { "locale": "ko-KR", "name": "DROP" }, { "locale": "lt-LT", "name": "DROP" }, { "locale": "lv-LV", "name": "DROP" }, { "locale": "nb-NO", "name": "DROP" }, { "locale": "nl-NL", "name": "WEGLATEN" }, { "locale": "pl-PL", "name": "POMIŃ" }, { "locale": "pt-BR", "name": "DROP" }, { "locale": "pt-PT", "name": "EXCLUIR" }, { "locale": "ro-RO", "name": "DROP" }, { "locale": "ru-RU", "name": "СБРОСИТЬ" }, { "locale": "sk-SK", "name": "DROP" }, { "locale": "sl-SI", "name": "DROP" }, { "locale": "sr-Latn-RS", "name": "DROP" }, { "locale": "sv-SE", "name": "UTESLUT" }, { "locale": "th-TH", "name": "DROP" }, { "locale": "tr-TR", "name": "BIRAK" }, { "locale": "uk-UA", "name": "DROP" }, { "locale": "vi-VN", "name": "DROP" }, { "locale": "zh-CN", "name": "DROP" }, { "locale": "zh-HK", "name": "DROP" }, { "locale": "zh-TW", "name": "DROP" } ], "signature": { "display": "DROP(array, rows, [columns])", "parameters": [ { "description": null, "name": "array", "optional": false, "repeats": false }, { "description": null, "name": "rows", "optional": false, "repeats": false }, { "description": null, "name": "columns", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "DROP", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/drop-function-1cb4e151-9e17-4838-abe5-9ba48d8c6a34" }, "try_it": { "formula": "=DROP({1,2;3,4},1)" }, "url": "https://handbook.dnacalc.com/functions/DROP.html", "variants": [], "versions": [] }