{
  "category": "Operators",
  "display_name": "Negation (-)",
  "entry_kind": "built_in_operator",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.OP_NEGATE",
  "implementation_state": {
    "answer_bank": null,
    "detail": "",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "unmeasured",
    "state_label": "Implemented, no recorded answers attributed to it",
    "summary": "Implemented; no recorded answers are attributed to this entry",
    "workbook_corpus": null
  },
  "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/arithmetic.rs#L43-L43",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/arithmetic.rs#L159-L174"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/arithmetic.rs#L43-L43",
      "state": "unmeasured",
      "suite": null,
      "summary": "Implemented; no recorded answers are attributed to this entry"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.OP_NEGATE.json",
  "name": "OP_NEGATE",
  "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- [`FUNC.OP_UNARY_PLUS`](FUNC.OP_UNARY_PLUS.md) — the deliberate contrast: same shape,\n  opposite coercion doctrine.\n- [`FUNC.OP_SUBTRACT`](FUNC.OP_SUBTRACT.md) — same character, two operands.\n- `ABS`, `SIGN` — the other sign-manipulating primitives. `-ABS(x)` is the idiomatic \"force\n  negative\"; `SIGN` does not distinguish `0` from `-0`.\n- `N`, `VALUE` — the explicit coercion functions. Where `--A` is used only for its coercion,\n  `N(A)` or `VALUE(A)` states the intent, though with different behaviour on text.\n- `IMSUB` — no relation, but readers looking for complex negation end up there.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n\n- Negate by flipping the sign bit, not by computing `0 - A`. The two differ on zero:\n  `0 - 0` is `+0` under round-to-nearest, while `-(0)` is `-0`.\n- The coercion must run *before* the negation and must be the shared to-number primitive, not\n  a local reimplementation — the whole point of the family module is that `-`, `%` and the\n  binary operators cannot drift apart on what counts as numeric text.\n- The elementwise array path must preserve element-local failures; do not short-circuit the\n  whole array on the first bad element.\n- Do not implement `+A` by delegating to this operator with the sign flip omitted. That is\n  precisely the shape `BUG-FUNC-029` records as a defect.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nReturns a `Number`.\n\n- **Text operands.** Numeric-looking text coerces and is negated; other text is a to-number\n  failure. Contrast with unary plus, where the recorded Excel observation is that text\n  survives as text.\n- **Logical operands.** `TRUE` becomes `-1`, `FALSE` becomes `0` (or `-0`) under the shared\n  rule.\n- **Empty and omitted.** Per-family policy under chapter 02; not recorded here for this\n  operator.\n- **Arrays.** The declared coercion/lift profile is\n  `CoercionLiftProfile::UnaryNumericScalarOrArrayElementwise` — one numeric argument, mapped\n  elementwise over arrays. A mixed array yields an array with element-local failures rather\n  than a collapsed error, per chapter 02.\n- **Zero.** Negating a zero yields a zero of the opposite sign. Whether that sign is\n  observable in a published Excel result is unrecorded here; the usual detector is dividing\n  into the result, but on the worksheet division by zero is an error either way, so a\n  detector has to be constructed carefully (`SIGN` will not see it, and neither will cell\n  display).\n\n\n",
    "sources": "- `data/presence/FUNC.OP_NEGATE.json` — implementing module\n  `earlier-implementation/operator_arithmetic_family.rs`.\n- Handbook `content/model/01-value-universe.md`, `02-coercion-and-lifting.md`,\n  `03-call-pipeline.md`.\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`-A` converts its single operand to a number and returns that number's negation.\n\nOn the arithmetic itself: negation of a binary64 value is exact. It flips the sign bit and\ntouches nothing else — there is no rounding, no overflow, and no underflow. Negation is one\nof the few operations in this Handbook about which nothing numerical can go wrong. The one\nconsequence worth remembering is that `-0` is a real, distinct binary64 value, and negating\nzero produces it.\n\n\n\n### Arguments\n\n\n| Position | Name | Meaning |\n|---|---|---|\n| 0 | `A` | The operand to negate. Required. |\n\nArity is exactly 1 (`Arity { min: 1, max: 1 }`); no optional arguments, no defaults.\n\nThe same `-` character in infix position is [`FUNC.OP_SUBTRACT`](FUNC.OP_SUBTRACT.md), a\ntwo-argument function. Which one a given `-` denotes is decided by the formula grammar, and\nformula grammar is out of this Handbook's scope (`CHARTER.md` section 4). The one place this\nbites readers is the double-unary idiom `--A`, which is two applications of this operator and\nis used precisely for its coercing effect: it turns logicals into 1/0 inside array\nexpressions.\n\n\n"
  },
  "signature": {
    "display": "-number",
    "parameters": [
      {
        "description": null,
        "name": "number",
        "optional": false,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 1,
        "min": 1
      },
      "category": "Operators",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "coercion_lift_profile": "UnaryNumericScalarOrArrayElementwise",
        "determinism_class": "Deterministic",
        "error_collapse_profile": "None",
        "fec_dependency_profile": "None",
        "host_interaction_class": "None",
        "kernel_signature_class": "NumToNum",
        "rich_value_usage": "RichBlind",
        "surface_fec_dependency_profile": "RefOnly",
        "thread_safety_class": "SafePure",
        "volatility_class": "NonVolatile"
      },
      "descriptions": {
        "long": null,
        "short": null,
        "short_source": "no-short-description"
      },
      "docs": null,
      "entry_kind": "built_in_operator",
      "localized_family_names": null,
      "localized_names": [],
      "signature": {
        "display": "-number",
        "parameters": [
          {
            "description": null,
            "name": "number",
            "optional": false,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "OP_NEGATE",
      "version_marker": null,
      "xlcall": null
    },
    "microsoft": null
  },
  "try_it": {
    "formula": "=-3"
  },
  "url": "https://handbook.dnacalc.com/functions/OP_NEGATE.html",
  "variants": [],
  "versions": []
}