Error formatting macro: pagetree: java.lang.NullPointerException
Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

This page is in progress and is the artifact for

Numbers and Math

As of version 1.3, Clojure provides full support for JVM primitive values, making it possible to write high performance, idiomatic Clojure code for numeric applications.

Numeric Types

  • Primitives - These are raw JVM primitives, not object references. They are by far the fastest way to do math on the JVM. Although it supports all primitives for the purposes of Java interoperability, for most purposes Clojure uses only long and double. Clojure will seamlessly promote ints to longs and floats to doubles as needed. When calling back to Java for interop, conversions to a smaller primitive type are checked for overflow, so no safety is lost.
  • Boxed Numbers - These are full objects that extend the java.lang.Number class. Clojure uses the full set of types built into the JVM (Integer, Long, BigInteger, Float, Double, BigDecimal) as well as two additional types:
    • clojure.lang.Ratio, for expressing rational numbers that cannot be expressed as a decimal without truncation
    • clojure.lang.BigInt, which is similar to Java's java.math.BigInteger in allowing integer sizes exceeding 64 bits, but provides better performance by delegating to native operations when small enough.


It is possible to create most types of numbers as literals directly within Clojure code:


Literal Syntax


primitive long (decimal)

a number, with no leading zeroes


primitive long (octal)

a number with a leading zero


primitive long (hexadecimal)

a number prefixed by 0x


primitive long (arbitrary base)

base + r + the number

2r101010, 12r36

primitive double (standard notation)

a number containing a decimal point

98.8, 3.3

primitive double (scientific notation)

coefficient + E + sign (optional) + exponent

6.0221479E+23, 6.67428E-11

rational number

number including a slash, with no spaces

1/3, 33/16

fixed point decimal (java.lang.BigDecimal)

number with M suffix


big integer (clojure.lang.BigInt)

number with N suffix, or a number too large to fit in a long

42N, 42000000000000000000

Math Operations

All of Clojure's mathematical functions and operators work polymorphically on all numeric types, primitive or boxed. When used on primitives, they will use native JVM operations for maximum speed.

When different types of numbers are used in a math operation, the result will be the larger or more general of the two types. For example, an operation involving a primitive long and a primitive double will result in a primitive double, and an operation between a primitive long and a BigInt will result in a BigInt. On other words, doubles and BigInts are "contagious" across operations. This is an intentional and useful feature, as it allows entire algorithms to be fully polymorphic based on their inputs. An algorithm written using standard operators will use fast native integer math when given primitive longs, fast native floating point math when given doubles, and will still function correctly, with no overflow, when a BigInt is introduced.

When a calcuation 


TODO: Document = and == and note which is used as map keys

Hinting, casting and coercions

TODO: Documentation of autoboxing, type hints on functions, coercion/casting functions

Usage notes