Negation (-)

What it does

-number

-A converts its single operand to a number and returns that number's negation.

On the arithmetic itself: negation of a binary64 value is exact. It flips the sign bit and touches nothing else — there is no rounding, no overflow, and no underflow. Negation is one of the few operations in this Handbook about which nothing numerical can go wrong. The one consequence worth remembering is that -0 is a real, distinct binary64 value, and negating zero produces it.

Arguments

Arity is exactly 1 (Arity { min: 1, max: 1 }); no optional arguments, no defaults.

The same - character in infix position is FUNC.OP_SUBTRACT, a two-argument function. Which one a given - denotes is decided by the formula grammar, and formula grammar is out of this Handbook's scope (CHARTER.md section 4). The one place this bites readers is the double-unary idiom --A, which is two applications of this operator and is used precisely for its coercing effect: it turns logicals into 1/0 inside array expressions.

Try it

Quirks

Result and edge cases

Returns a Number.

• Text operands. Numeric-looking text coerces and is negated; other text is a to-number failure. Contrast with unary plus, where the recorded Excel observation is that text survives as text.
• Logical operands. TRUE becomes -1, FALSE becomes 0 (or -0) under the shared rule.
• Empty and omitted. Per-family policy under chapter 02; not recorded here for this operator.
• Arrays. The declared coercion/lift profile is CoercionLiftProfile::UnaryNumericScalarOrArrayElementwise — one numeric argument, mapped elementwise over arrays. A mixed array yields an array with element-local failures rather than a collapsed error, per chapter 02.
• Zero. Negating a zero yields a zero of the opposite sign. Whether that sign is observable in a published Excel result is unrecorded here; the usual detector is dividing into the result, but on the worksheet division by zero is an error either way, so a detector has to be constructed carefully (SIGN will not see it, and neither will cell display).

How to implement

Notes for implementers

• Negate by flipping the sign bit, not by computing 0 - A. The two differ on zero: 0 - 0 is +0 under round-to-nearest, while -(0) is -0.
• The coercion must run before the negation and must be the shared to-number primitive, not a local reimplementation — the whole point of the family module is that -, % and the binary operators cannot drift apart on what counts as numeric text.
• The elementwise array path must preserve element-local failures; do not short-circuit the whole array on the first bad element.
• Do not implement +A by delegating to this operator with the sign flip omitted. That is precisely the shape BUG-FUNC-029 records as a defect.

Rust code

CatalogueEntry::operator(NEGATE, "-", Notation::Prefix, NUMBER, negate)

/// `-x`: the sign changes exactly, so no rounding takes place.
fn negate(
    arguments: &[CalcValue],
    services: &mut EvalServices<'_>,
) -> Result<CalcValue, FunctionFault> {
    // Excel keeps the entire stored overflow encoding, including its sign bit.
    if arguments[0].is_excel_overflow() {
        return Ok(arguments[0].clone());
    }
    let site = Site::new(NEGATE, services);
    Site::finish(
        site.scalar_operands(arguments)
            .and_then(|()| site.number_argument(0, &arguments[0]))
            .and_then(|x| site.number(-x)),
    )
}

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• FUNC.OP_UNARY_PLUS — the deliberate contrast: same shape, opposite coercion doctrine.
• FUNC.OP_SUBTRACT — same character, two operands.
• ABS, SIGN — the other sign-manipulating primitives. -ABS(x) is the idiomatic "force negative"; SIGN does not distinguish 0 from -0.
• N, VALUE — the explicit coercion functions. Where --A is used only for its coercion, N(A) or VALUE(A) states the intent, though with different behaviour on text.
• IMSUB — no relation, but readers looking for complex negation end up there.

Named variants

No named variants are recorded yet.