How deeply does Clojure: The Essential Reference cover unchecked-add-int?

Defines arity, input range, int casting, return type, and overflow behavior, with examples rather than implementation internals.

Unchecked-add-int

As explained in Clojure: The Essential Reference

unchecked-add-int is a Clojure function that adds two numeric values as primitive 32-bit signed integers without overflow checking.

`unchecked-add-int` adds two numbers using 32-bit signed integer arithmetic. It is useful when an algorithm needs `int` results rather than Clojure’s usual `long` arithmetic, as in hashing or integer-based image processing. section 5.14

Its contract is narrow:

It takes exactly two numeric arguments within the signed `int` range and casts them to primitive `int` values. section 5.14
It returns an `int` result without checking for overflow. A result beyond `Integer/MAX_VALUE` rolls over to the negative end of the range. section 5.14 section 5.1

Casting and rollover

`(unchecked-add-int 2.0 1)` returns `3`; `(type (unchecked-add-int 2.0 1))` returns `java.lang.Integer`. By contrast, `(unchecked-add 2.0 1)` returns `3.0`. At the boundary, `(unchecked-add-int Integer/MAX_VALUE 1)` returns `Integer/MIN_VALUE`. section 5.14 section 5.1

Choose `unchecked-add-int` when 32-bit results and possible rollover are intentional. Ordinary `+` checks for overflow and promotes `int` operands to `long`; the unchecked operators without the `-int` suffix do not force an `int` result. Related functions provide unchecked subtraction, multiplication, division, increment, decrement, negation, and remainder on `int` values. section 5.5 section 5.14

32 bits	decimal value	relative value
`01111111111111111111111111111101`	2147483645	(- Integer/MAX_VALUE 2)
`01111111111111111111111111111110`	2147483646	(- Integer/MAX_VALUE 1)
`01111111111111111111111111111111`	2147483647	Integer/MAX_VALUE, (unchecked-subtract-int Integer/MIN_VALUE 1)
`10000000000000000000000000000000`	-2147483648	Integer/MIN_VALUE, (unchecked-add-int Integer/MAX_VALUE 1)
`10000000000000000000000000000001`	-2147483647	(+ Integer/MIN_VALUE 1)
`10000000000000000000000000000010`	-2147483646	(+ Integer/MIN_VALUE 2)

The 32-bit value table shows the sign change when adding one to the largest signed `int`. section 5.1

How Clojure: The Essential Reference covers it

Cover of Clojure: The Essential Reference

liveBook manning.com

Read Clojure: The Essential Reference on liveBook Get the book at manning.com

Related concepts

integeruses · An integer is a whole-number value with no fractional part, including negative numbers, zero, and positive numbers.
numerical overflowuses · Numerical overflow is the condition in which an arithmetic result falls outside the range representable by its numeric type or format.
unchecked-incalternative to · unchecked-inc is a Clojure function that increments a numeric value without checking for numeric overflow.
unchecked-inc-intalternative to · unchecked-inc-int is a Clojure function that increments using Java Integer arithmetic without implicit promotion to Long or overflow checking.
unchecked-multiplycontrasts with · unchecked-multiply is a Clojure function that multiplies two numeric arguments without checking for integer overflow.
unchecked-negate-intalternative to · unchecked-negate-int is a Clojure function that negates a numeric value as a primitive 32-bit signed integer without overflow checking.

This explainer was generated by Manning's knowledge graph from the text of Clojure: The Essential Reference. The section links point to the parts of the book it draws on.