Dwayne Crooks

Posted on

# Announcing elm-integer

I am happy to announce the release of `elm-integer`.

`elm-integer` is a pure Elm library for computing with the integers, ℤ = { ..., -2, -1, 0, 1, 2, ... }. It uses arbitrary-precision arithmetic so the magnitude of the numbers you can compute with is only limited by the available memory. It is extensively tested for correctness and has reasonable performance characteristics.

## Try it out

I built an integer calculator that allows you to test out all the integer input formats, arithmetic operations, and integer output formats that's supported by `elm-integer`. Feel free to use the calculator to explore the limits of the library.

## Compared to `cmditch/elm-bigint`

### Commonly used small integers are named

The integers from `-10` to `10` are already named. In particular, `zero`, `one`, `two`, `ten`, and `negativeOne` are available for immediate use.

### Large integers are easy to create

`fromSafeString` is useful for establishing large constants in a calculation.

### Multiple integer input formats are supported

Any base from 2 to 36 is supported using `fromBaseBString` and shortcuts are provided for binary, octal, decimal, and hexadecimal input formats.

### Multiple integer output formats are supported

Any base from 2 to 36 is supported using `toBaseBString` and shortcuts are provided for binary, octal, decimal, and hexadecimal output formats.

### There are useful predicates

With these predicates it's easy to check if your integer is zero (`== 0`), negative (`< 0`), non-negative (`>= 0`), positive (`> 0`), or non-positive (`<= 0`).

`==` and `/=` work as expected so if you wanted to know if your integer, `z`, is equal to `-1` then `z == negativeOne` is all you have to do.

### Arithmetic is performant

This library is built on `elm-natural` which currently outperforms `cmditch/elm-bigint` in multiplication, division with remainder, and exponentiation.

### `divModBy` defines Euclidean division

`cmditch/elm-bigint`'s `divmod` operation defines truncated division (or T-division) according to Daan Leijen's paper, Division and Modulus for Computer Scientists. It is the equivalent of `quot`/`rem` in Haskell. No equivalent of Euclidean division is provided.

N.B. You can check out this Ellie of `divmod` to confirm the above statements.

However, Boute argues that Euclidean division is superior to the other definitions of the div and mod functions in terms of regularity and useful mathematical properties.

Hence, `divModBy` in `elm-integer` defines Euclidean division and truncated division is provided by `quotRemBy`.

## Feedback is appreciated

If you happen to use the library in an application, I would greatly appreciate your feedback.