Clojure Numeric API

1. Arithmetic Functions

Function Description Examples

\((\texttt{+}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 + x_2 + \cdots + x_n\). Returns 0 if no arguments are specified. Throws an ArithmeticException if an overflow is produced when using arguments of type Long.

(+ 1 2 3 4 5)
=> 15
(+)
=> 0
(+ Long/MAX_VALUE 1)
=> ArithmeticException

\((\texttt{+'}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 + x_2 + \cdots + x_n\). Returns 0 if no arguments are specified. Converts result automatically into BigInt if an overflow is produced when using arguments of type Long.

(+' 1 2 3 4 5)
=> 15
(+')
=> 0
(+' Long/MAX_VALUE 1)
=> 9223372036854775808N

\((\texttt{inc}\;x)\)

Returns \(x + 1\). Throws an ArithmeticException if an overflow is produced when its argument is of type Long.

(inc 5)
=> 6
(inc -5)
=> -4
(inc Long/MAX_VALUE)
=> ArithmeticException

\((\texttt{inc'}\;x)\)

Returns \(x + 1\). Converts result automatically into BigInt if an overflow is produced when its argument is of type Long.

(inc' 5)
=> 6
(inc' -5)
=> -4
(inc' Long/MAX_VALUE)
=> 9223372036854775808N

\((\texttt{-}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 - x_2 - \cdots - x_n\). Returns \(-x_1\) if only one argument is provided. Throws an ArithmeticException if an overflow is produced when using arguments of type Long.

(- 10 1 2 3)
=> 4
(- 10)
=> -10
(- Long/MIN_VALUE 1)
=> ArithmeticException

\((\texttt{-'}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 - x_2 - \cdots - x_n\). Returns \(-x_1\) if only one argument is provided. Converts result automatically into BigInt if an overflow is produced when using arguments of type Long.

(-' 10 1 2 3)
=> 4
(-' 10)
=> -10
(-' Long/MIN_VALUE 1)
=> -9223372036854775809N

\((\texttt{dec}\;x)\)

Returns \(x - 1\). Throws an ArithmeticException if an overflow is produced when its argument is of type Long.

(dec 5)
=> 4
(dec -5)
=> -6
(dec Long/MIN_VALUE)
=> ArithmeticException

\((\texttt{dec'}\;x)\)

Returns \(x - 1\). Converts result automatically into BigInt if an overflow is produced when its argument is of type Long.

(dec' 5)
=> 4
(dec' -5)
=> -6
(dec' Long/MIN_VALUE)
=> -9223372036854775809N

\((\texttt{*}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 \times x_2 \times \cdots \times x_n\). Returns 1 if no arguments are specified. Throws an ArithmeticException if an overflow is produced when using arguments of type Long.

(* 1 2 3 4 5)
=> 120
(*)
=> 1
(* Long/MAX_VALUE 2)
=> ArithmeticException

\((\texttt{*'}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 \times x_2 \times \cdots \times x_n\). Returns 1 if no arguments are specified. Converts result automatically into BigInt if an overflow is produced when using arguments of type Long.

(*' 1 2 3 4 5)
=> 120
(*')
=> 1
(*' Long/MAX_VALUE 2)
=> 18446744073709551614N

\((\texttt{/}\;x_1\;x_2\;\ldots\;x_n)\)

Returns \(x_1 \div x_2 \div \cdots \div x_n\). Returns \(\frac{1}{x_1}\) if only one argument is provided.

(/ 20 2 5)
=> 2
(/ 1 2)
=> 1/2
(/ 10.0)
=> 0.1

\((\texttt{quot}\;x\;y)\)

Returns the integer quotient of dividing \(x\) by \(y\).

(quot 20 3)
=> 6
(quot -20 3)
=> -6
(quot -20 -3)
=> 6

\((\texttt{rem}\;x\;y)\)

Returns the remainder of dividing \(x\) by \(y\).

If \(a\) is \((\texttt{quot}\;x\;y)\), and \(b\) is \((\texttt{rem}\;x\;y)\), then it holds true that: \((a \times y) + b = x\)

(rem 20 3)
=> 2
(rem -20 3)
=> -2
(rem 20 -3)
=> 2
(rem -20 -3)
=> -2

\((\texttt{mod}\;x\;y)\)

Returns \(x \bmod y \) (modulus of \(x\) and \(y\)). This is basically equivalent to:

\(\texttt{(- } x \;\texttt{(* (}\texttt{Math/floor }\texttt{(/ } x\;y\texttt{)) }y\texttt{))}\)

\((\texttt{mod}\;x\;y)\) and \((\texttt{rem}\;x\;y)\) produce the same results when \(x\) and \(y\) have the same sign, but this is not necessarily true otherwise.

(mod 20 3)
=> 2
(mod -20 3)
=> 1
(mod 20 -3)
=> -1
(mod -20 -3)
=> -2

2. Numerical Predicates

Function Description Examples

Function	Description	Examples
\((\texttt{zero?}\;x)\)	Returns `true` if \(x\) is zero, otherwise returns `false`.	`(zero? 0) => true (zero? 42) => false (zero? 0.0) => true`
\((\texttt{pos?}\;x)\)	Returns `true` if \(x\) is a number greater than zero, otherwise returns `false`.	`(pos? 42) => true (pos? -10) => false (pos? 0) => false`
\((\texttt{neg?}\;x)\)	Returns `true` if \(x\) is a number less than zero, otherwise returns `false`.	`(neg? 42) => false (neg? -10) => true (neg? 0) => false`
\((\texttt{even?}\;x)\)	Returns `true` if \(x\) is an even number, otherwise returns `false`. Throws an `IllegalArgumentException` if \(x\) is not an integer.	`(even? 10) => true (even? 15) => false (even? 2.0) => IllegalArgumentException`
\((\texttt{odd?}\;x)\)	Returns `true` if \(x\) is an odd number, otherwise returns `false`. Throws an `IllegalArgumentException` if \(x\) is not an integer.	`(odd? 10) => false (odd? 15) => true (odd? 2.0) => IllegalArgumentException`

\((\texttt{zero?}\;x)\)

Returns true if \(x\) is zero, otherwise returns false.

(zero? 0)
=> true
(zero? 42)
=> false
(zero? 0.0)
=> true

\((\texttt{pos?}\;x)\)

Returns true if \(x\) is a number greater than zero, otherwise returns false.

(pos? 42)
=> true
(pos? -10)
=> false
(pos? 0)
=> false

\((\texttt{neg?}\;x)\)

Returns true if \(x\) is a number less than zero, otherwise returns false.

(neg? 42)
=> false
(neg? -10)
=> true
(neg? 0)
=> false

\((\texttt{even?}\;x)\)

Returns true if \(x\) is an even number, otherwise returns false. Throws an IllegalArgumentException if \(x\) is not an integer.

(even? 10)
=> true
(even? 15)
=> false
(even? 2.0)
=> IllegalArgumentException

\((\texttt{odd?}\;x)\)

Returns true if \(x\) is an odd number, otherwise returns false. Throws an IllegalArgumentException if \(x\) is not an integer.

(odd? 10)
=> false
(odd? 15)
=> true
(odd? 2.0)
=> IllegalArgumentException

3. Comparison Functions

Function Description Examples

\((\texttt{=}\;x_1\;x_2\;\ldots\;x_n)\)

Returns true if \(x_1 = x_2 = \cdots = x_n\), otherwise returns false. Two numbers \(x_1\) and \(x_2\) are equal only if both have the same type and the same value.

This function also works with non-numeric values.

(= (* 3 1)
   (+ 2 1)
   (/ 12 4))
=> true
(= (* 2 3) (+ 2 3))
=> false
(= 1 1.0)
=> false

\((\texttt{==}\;x_1\;x_2\;\ldots\;x_n)\)

Returns true if all numbers \(x_1, x_2, \ldots, x_n\) have equivalent type-independent values, otherwise returns false.

(== (* 3 1)
    (+ 2 1)
    (/ 12 4))
=> true
(== (* 2 3) (+ 2 3))
=> false
(== 1 1.0)
=> true

\((\texttt{not=}\;x_1\;x_2\;\ldots\;x_n)\)

Same as \((\texttt{not}\;(\texttt{=}\;x_1\;x_2\;\ldots\;x_n))\).

This function also works with non-numeric values.

(not= (* 3 1)
      (+ 2 1)
      (/ 12 4))
=> false
(not= (* 2 3) (+ 2 3))
=> true
(not= 1 1.0)
=> true

\((\texttt{<}\;x_1\;x_2\;\ldots\;x_n)\)

Returns true if \(x_1 < x_2 < \cdots < x_n\), otherwise returns false.

(< 1 2 3 4 5)
=> true
(< 1 2 3 3 4)
=> false
(< 10 4)
=> false

\((\texttt{<=}\;x_1\;x_2\;\ldots\;x_n)\)

Returns true if \(x_1 \leqslant x_2 \leqslant \cdots \leqslant x_n\), otherwise returns false.

(<= 1 2 3 4 5)
=> true
(<= 1 2 3 3 4)
=> true
(<= 10 4)
=> false

\((\texttt{>}\;x_1\;x_2\;\ldots\;x_n)\)

Returns true if \(x_1 > x_2 > \cdots > x_n\), otherwise returns false.

(> 5 4 3 2 1)
=> true
(> 5 4 4 3 2)
=> false
(> 4 10)
=> false

\((\texttt{>=}\;x_1\;x_2\;\ldots\;x_n)\)

Returns true if \(x_1 \geqslant x_2 \geqslant \cdots \geqslant x_n\), otherwise returns false.

(>= 5 4 3 2 1)
=> true
(>= 5 4 4 3 2)
=> true
(>= 4 10)
=> false

4. Random Numbers

Function Description Examples

Function	Description	Examples
\((\texttt{rand})\) \((\texttt{rand}\;n)\)	Returns a random floating point number \(r\), where \(0 \leqslant r < n\). If \(n\) is omitted it defaults to 1.	`(rand) => 0.3473911330833691 (rand 100) => 87.43000630622653`
\((\texttt{rand-int}\;n)\)	Returns a random integer number \(r\), where \(0 \leqslant r < n\).	`(rand-int 10) => 4 (rand-int 100) => 63`

\((\texttt{rand})\)

\((\texttt{rand}\;n)\)

Returns a random floating point number \(r\), where \(0 \leqslant r < n\). If \(n\) is omitted it defaults to 1.

(rand)
=> 0.3473911330833691
(rand 100)
=> 87.43000630622653

\((\texttt{rand-int}\;n)\)

Returns a random integer number \(r\), where \(0 \leqslant r < n\).

(rand-int 10)
=> 4
(rand-int 100)
=> 63

5. Numeric Tower Functions

These are math functions that deal intelligently with the various types in Clojure’s numeric tower.

To use these functions, you need to import the corresponding namespace, something like this:

(use 'clojure.math.numeric-tower)

Function Description Examples

Function	Description	Examples
\((\texttt{abs}\;x)\)	Returns \(\left \| x \right \|\) (absolute value of \(x\)).	`(abs -5) => 5 (abs 12N) => 12N (abs -1.2) => 1.2`
\((\texttt{sqrt}\;x)\)	Returns \(\sqrt{x}\) (square root of \(x\)), exact if possible.	`(sqrt 25) => 5 (sqrt 2) => 1.4142135623730951 (sqrt -1) => ##NaN`
\((\texttt{expt}\;x\;y)\)	Returns \(x^y\) (\(x\) raised to the power \(y\)).	`(expt 2 10) => 1024 (expt 2 1/2) => 1.4142135623730951 (expt 2 -3) => 1/8`
\((\texttt{round}\;x)\)	Returns \(\left \lfloor x \right \rceil\) (\(x\) rounded to the nearest integer). Rounds up for values exactly in between two integers. The result is always an integer.	`(round 1.2) => 1 (round 1.5M) => 2N (round -2.9) => -3`
\((\texttt{ceil}\;x)\)	Returns \(\left \lceil x \right \rceil\) (least integer greater than or equal to \(x\), or in other words, \(x\) rounded towards \(+\infty\)). If \(x\) is an exact number, returns an integer, otherwise a double.	`(ceil 1.2) => 2.0 (ceil 1.5M) => 2N (ceil -2.9) => -2.0 (ceil 1/8) => 1N`
\((\texttt{floor}\;x)\)	Returns \(\left \lfloor x \right \rfloor\) (greatest integer less than or equal to \(x\), or in other words, \(x\) rounded towards \(-\infty\)). If \(x\) is an exact number, returns an integer, otherwise a double.	`(floor 1.2) => 1.0 (floor 1.5M) => 1N (floor -2.9) => -3.0 (floor 1/8) => 0N`
\((\texttt{gcd}\;x\;y)\)	Returns the greatest common divisor of \(x\) and \(y\). Arguments must be integers.	`(gcd 8 12) => 4`
\((\texttt{lcm}\;x\;y)\)	Returns the least common multiple of \(x\) and \(y\). Arguments must be integers.	`(lcm 8 12) => 24`

\((\texttt{abs}\;x)\)

Returns \(\left | x \right |\) (absolute value of \(x\)).

(abs -5)
=> 5
(abs 12N)
=> 12N
(abs -1.2)
=> 1.2

\((\texttt{sqrt}\;x)\)

Returns \(\sqrt{x}\) (square root of \(x\)), exact if possible.

(sqrt 25)
=> 5
(sqrt 2)
=> 1.4142135623730951
(sqrt -1)
=> ##NaN

\((\texttt{expt}\;x\;y)\)

Returns \(x^y\) (\(x\) raised to the power \(y\)).

(expt 2 10)
=> 1024
(expt 2 1/2)
=> 1.4142135623730951
(expt 2 -3)
=> 1/8

\((\texttt{round}\;x)\)

Returns \(\left \lfloor x \right \rceil\) (\(x\) rounded to the nearest integer). Rounds up for values exactly in between two integers. The result is always an integer.

(round 1.2)
=> 1
(round 1.5M)
=> 2N
(round -2.9)
=> -3

\((\texttt{ceil}\;x)\)

Returns \(\left \lceil x \right \rceil\) (least integer greater than or equal to \(x\), or in other words, \(x\) rounded towards \(+\infty\)). If \(x\) is an exact number, returns an integer, otherwise a double.

(ceil 1.2)
=> 2.0
(ceil 1.5M)
=> 2N
(ceil -2.9)
=> -2.0
(ceil 1/8)
=> 1N

\((\texttt{floor}\;x)\)

Returns \(\left \lfloor x \right \rfloor\) (greatest integer less than or equal to \(x\), or in other words, \(x\) rounded towards \(-\infty\)). If \(x\) is an exact number, returns an integer, otherwise a double.

(floor 1.2)
=> 1.0
(floor 1.5M)
=> 1N
(floor -2.9)
=> -3.0
(floor 1/8)
=> 0N

\((\texttt{gcd}\;x\;y)\)

Returns the greatest common divisor of \(x\) and \(y\). Arguments must be integers.

(gcd 8 12)
=> 4

\((\texttt{lcm}\;x\;y)\)

Returns the least common multiple of \(x\) and \(y\). Arguments must be integers.

(lcm 8 12)
=> 24