# API for math - clojure-contribv1.2 (stable)

by Mark Engelberg

### clojure-contrib is now deprecated

clojure-contrib is no longer being developed or maintained.

Rather than a single, monolithic, contributions library, Clojure now has a set of separate libraries for each unit of functionality. The libraries are in the Clojure GitHub organization at https://github.com/clojure. API documentation of the libraries can be found at https://clojure.github.io.

If you're looking for a specific function or namespace from the old clojure-contrib, see "Where Did Clojure.Contrib Go".

Full namespace name: clojure.contrib.math

## Overview

```Math functions that deal intelligently with the various
types in Clojure's numeric tower, as well as math functions
commonly found in Scheme implementations.

expt - (expt x y) is x to the yth power, returns an exact number
if the base is an exact number, and the power is an integer,
otherwise returns a double.
abs - (abs n) is the absolute value of n
gcd - (gcd m n) returns the greatest common divisor of m and n
lcm - (lcm m n) returns the least common multiple of m and n

The behavior of the next three functions on doubles is consistent
with the behavior of the corresponding functions
in Java's Math library, but on exact numbers, returns an integer.

floor - (floor n) returns the greatest integer less than or equal to n.
If n is an exact number, floor returns an integer,
otherwise a double.
ceil - (ceil n) returns the least integer greater than or equal to n.
If n is an exact number, ceil returns an integer,
otherwise a double.
round - (round n) rounds to the nearest integer.
round always returns an integer.  round rounds up for values
exactly in between two integers.

sqrt - Implements the sqrt behavior I'm accustomed to from PLT Scheme,
specifically, if the input is an exact number, and is a square
of an exact number, the output will be exact.  The downside
is that for the common case (inexact square root), some extra
computation is done to look for an exact square root first.
So if you need blazingly fast square root performance, and you
know you're just going to need a double result, you're better
off calling java's Math/sqrt, or alternatively, you could just
convert your input to a double before calling this sqrt function.
If Clojure ever gets complex numbers, then this function will
need to be updated (so negative inputs yield complex outputs).
exact-integer-sqrt - Implements a math function from the R6RS Scheme
standard.  (exact-integer-sqrt k) where k is a non-negative integer,
returns [s r] where k = s^2+r and k < (s+1)^2.  In other words, it
returns the floor of the square root and the ```

## abs

function
```Usage: (abs n)
```
`(abs n) is the absolute value of n`
Source

## ceil

multimethod
```Usage: (ceil n)
```
```(ceil n) returns the least integer greater than or equal to n.
If n is an exact number, ceil returns an integer, otherwise a double.```
Source

## exact-integer-sqrt

function
```Usage: (exact-integer-sqrt n)
```
```(exact-integer-sqrt n) expects a non-negative integer n, and returns [s r] where n = s^2+r and n < (s+1)^2.  In other words, it returns the floor of the square root and the 'remainder'.
For example, (exact-integer-sqrt 15) is [3 6] because 15 = 3^2+6.```
Source

## expt

multimethod
```Usage: (expt base pow)
```
```(expt base pow) is base to the pow power.
Returns an exact number if the base is an exact number and the power is an integer, otherwise returns a double.```
Source

## floor

multimethod
```Usage: (floor n)
```
```(floor n) returns the greatest integer less than or equal to n.
If n is an exact number, floor returns an integer, otherwise a double.```
Source

## gcd

function
```Usage: (gcd a b)
```
`(gcd a b) returns the greatest common divisor of a and b`
Source

## lcm

function
```Usage: (lcm a b)
```
`(lcm a b) returns the least common multiple of a and b`
Source

## round

multimethod
```Usage: (round n)
```
```(round n) rounds to the nearest integer.
round always returns an integer.  Rounds up for values exactly in between two integers.```
Source

## sqrt

multimethod
```Usage: (sqrt n)
`Square root, but returns exact number if possible.`