# gleam/int

Functions for working with integers.

## Division by zero

In Erlang division by zero results in a crash, however Gleam does not have partial functions and operators in core so instead division by zero returns zero, a behaviour taken from Pony, Coq, and Lean.

This may seem unexpected at first, but it is no less mathematically valid than crashing or returning a special value. Division by zero is undefined in mathematics.

# Types

## InvalidBase

</>

Error value when trying to operate with a base out of the allowed range.

``````pub type InvalidBase {
InvalidBase
}``````

### Constructors

• ``InvalidBase``

# Functions

## absolute_value

</>
``pub fn absolute_value(x: Int) -> Int``

Returns the absolute value of the input.

## Examples

``````absolute_value(-12)
// -> 12
``````
``````absolute_value(10)
// -> 10
``````

</>
``pub fn add(a: Int, b: Int) -> Int``

It’s the function equivalent of the `+` operator. This function is useful in higher order functions or pipes.

## Examples

``````add(1, 2)
// -> 3
``````
``````import gleam/list
// -> 6
``````
``````3 |> add(2)
// -> 5
``````

## base_parse

</>
``pub fn base_parse(string: String, base: Int) -> Result(Int, Nil)``

Parses a given string as an int in a given base if possible. Supports only bases 2 to 36, for values outside of which this function returns an `Error(Nil)`.

## Examples

``````base_parse("10", 2)
// -> Ok(2)
``````
``````base_parse("30", 16)
// -> Ok(48)
``````
``````base_parse("1C", 36)
// -> Ok(48)
``````
``````base_parse("48", 1)
// -> Error(Nil)
``````
``````base_parse("48", 37)
// -> Error(Nil)
``````

## bitwise_and

</>
``pub fn bitwise_and(x: Int, y: Int) -> Int``

Calculates the bitwise AND of its arguments.

The exact behaviour of this function depends on the target platform. On Erlang it is equivalent to bitwise operations on ints, on JavaScript it is equivalent to bitwise operations on big-ints.

## bitwise_exclusive_or

</>
``pub fn bitwise_exclusive_or(x: Int, y: Int) -> Int``

Calculates the bitwise XOR of its arguments.

The exact behaviour of this function depends on the target platform. On Erlang it is equivalent to bitwise operations on ints, on JavaScript it is equivalent to bitwise operations on big-ints.

## bitwise_not

</>
``pub fn bitwise_not(x: Int) -> Int``

Calculates the bitwise NOT of its argument.

The exact behaviour of this function depends on the target platform. On Erlang it is equivalent to bitwise operations on ints, on JavaScript it is equivalent to bitwise operations on big-ints.

## bitwise_or

</>
``pub fn bitwise_or(x: Int, y: Int) -> Int``

Calculates the bitwise OR of its arguments.

The exact behaviour of this function depends on the target platform. On Erlang it is equivalent to bitwise operations on ints, on JavaScript it is equivalent to bitwise operations on big-ints.

## bitwise_shift_left

</>
``pub fn bitwise_shift_left(x: Int, y: Int) -> Int``

Calculates the result of an arithmetic left bitshift.

The exact behaviour of this function depends on the target platform. On Erlang it is equivalent to bitwise operations on ints, on JavaScript it is equivalent to bitwise operations on big-ints.

## bitwise_shift_right

</>
``pub fn bitwise_shift_right(x: Int, y: Int) -> Int``

Calculates the result of an arithmetic right bitshift.

The exact behaviour of this function depends on the target platform. On Erlang it is equivalent to bitwise operations on ints, on JavaScript it is equivalent to bitwise operations on big-ints.

## clamp

</>
``````pub fn clamp(
x: Int,
min min_bound: Int,
max max_bound: Int,
) -> Int``````

Restricts an int between a lower and upper bound.

## Examples

``````clamp(40, min: 50, max: 60)
// -> 50
``````

## compare

</>
``pub fn compare(a: Int, with b: Int) -> Order``

Compares two ints, returning an order.

## Examples

``````compare(2, 3)
// -> Lt
``````
``````compare(4, 3)
// -> Gt
``````
``````compare(3, 3)
// -> Eq
``````

## digits

</>
``````pub fn digits(
x: Int,
base: Int,
) -> Result(List(Int), InvalidBase)``````

Splits an integer into its digit representation in the specified base

## Examples

``````digits(234, 10)
// -> Ok([2,3,4])
``````
``````digits(234, 1)
// -> Error(InvalidBase)
``````

## divide

</>
``pub fn divide(dividend: Int, by divisor: Int) -> Result(Int, Nil)``

Performs a truncated integer division.

Returns division of the inputs as a `Result`: If the given divisor equals `0`, this function returns an `Error`.

## Examples

``````divide(0, 1)
// -> Ok(0)
``````
``````divide(1, 0)
// -> Error(Nil)
``````
``````divide(5, 2)
// -> Ok(2)
``````
``````divide(-99, 2)
// -> Ok(-49)
``````

## floor_divide

</>
``````pub fn floor_divide(
dividend: Int,
by divisor: Int,
) -> Result(Int, Nil)``````

Performs a floored integer division, which means that the result will always be rounded towards negative infinity.

If you want to perform truncated integer division (rounding towards zero), use `int.divide()` or the `/` operator instead.

Returns division of the inputs as a `Result`: If the given divisor equals `0`, this function returns an `Error`.

## Examples

``````floor_divide(1, 0)
// -> Error(Nil)
``````
``````floor_divide(5, 2)
// -> Ok(2)
``````
``````floor_divide(6, -4)
// -> Ok(-2)
``````
``````floor_divide(-99, 2)
// -> Ok(-50)
``````

## is_even

</>
``pub fn is_even(x: Int) -> Bool``

Returns whether the value provided is even.

## Examples

``````is_even(2)
// -> True
``````
``````is_even(3)
// -> False
``````

## is_odd

</>
``pub fn is_odd(x: Int) -> Bool``

Returns whether the value provided is odd.

## Examples

``````is_odd(3)
// -> True
``````
``````is_odd(2)
// -> False
``````

## max

</>
``pub fn max(a: Int, b: Int) -> Int``

Compares two ints, returning the larger of the two.

## Examples

``````max(2, 3)
// -> 3
``````

## min

</>
``pub fn min(a: Int, b: Int) -> Int``

Compares two ints, returning the smaller of the two.

## Examples

``````min(2, 3)
// -> 2
``````

## modulo

</>
``pub fn modulo(dividend: Int, by divisor: Int) -> Result(Int, Nil)``

Computes the modulo of an integer division of inputs as a `Result`.

Returns division of the inputs as a `Result`: If the given divisor equals `0`, this function returns an `Error`.

Most the time you will want to use the `%` operator instead of this function.

## Examples

``````modulo(3, 2)
// -> Ok(1)
``````
``````modulo(1, 0)
// -> Error(Nil)
``````
``````modulo(10, -1)
// -> Ok(0)
``````
``````modulo(13, by: 3)
// -> Ok(1)
``````
``````modulo(-13, by: 3)
// -> Ok(2)
``````

## multiply

</>
``pub fn multiply(a: Int, b: Int) -> Int``

Multiplies two integers together.

It’s the function equivalent of the `*` operator. This function is useful in higher order functions or pipes.

## Examples

``````multiply(2, 4)
// -> 8
``````
``````import gleam/list

list.fold([2, 3, 4], 1, multiply)
// -> 24
``````
``````3 |> multiply(2)
// -> 6
``````

## negate

</>
``pub fn negate(x: Int) -> Int``

Returns the negative of the value provided.

## Examples

``````negate(1)
// -> -1
``````

## parse

</>
``pub fn parse(string: String) -> Result(Int, Nil)``

Parses a given string as an int if possible.

## Examples

``````parse("2")
// -> Ok(2)
``````
``````parse("ABC")
// -> Error(Nil)
``````

## power

</>
``pub fn power(base: Int, of exponent: Float) -> Result(Float, Nil)``

Returns the results of the base being raised to the power of the exponent, as a `Float`.

## Examples

``````power(2, -1.0)
// -> Ok(0.5)
``````
``````power(2, 2.0)
// -> Ok(4.0)
``````
``````power(8, 1.5)
// -> Ok(22.627416997969522)
``````
``````4 |> power(of: 2.0)
// -> Ok(16.0)
``````
``````power(-1, 0.5)
// -> Error(Nil)
``````

## product

</>
``pub fn product(numbers: List(Int)) -> Int``

Multiplies a list of ints and returns the product.

## Example

``````product([2, 3, 4])
// -> 24
``````

## random

</>
``pub fn random(max: Int) -> Int``

Generates a random int between zero and the given maximum.

The lower number is inclusive, the upper number is exclusive.

## Examples

``````random(10)
// -> 4
``````
``````random(1)
// -> 0
``````
``````random(-1)
// -> -1
``````

## remainder

</>
``````pub fn remainder(
dividend: Int,
by divisor: Int,
) -> Result(Int, Nil)``````

Computes the remainder of an integer division of inputs as a `Result`.

Returns division of the inputs as a `Result`: If the given divisor equals `0`, this function returns an `Error`.

Most the time you will want to use the `%` operator instead of this function.

## Examples

``````remainder(3, 2)
// -> Ok(1)
``````
``````remainder(1, 0)
// -> Error(Nil)
``````
``````remainder(10, -1)
// -> Ok(0)
``````
``````remainder(13, by: 3)
// -> Ok(1)
``````
``````remainder(-13, by: 3)
// -> Ok(-1)
``````
``````remainder(13, by: -3)
// -> Ok(1)
``````
``````remainder(-13, by: -3)
// -> Ok(-1)
``````

## square_root

</>
``pub fn square_root(x: Int) -> Result(Float, Nil)``

Returns the square root of the input as a `Float`.

## Examples

``````square_root(4)
// -> Ok(2.0)
``````
``````square_root(-16)
// -> Error(Nil)
``````

## subtract

</>
``pub fn subtract(a: Int, b: Int) -> Int``

Subtracts one int from another.

It’s the function equivalent of the `-` operator. This function is useful in higher order functions or pipes.

## Examples

``````subtract(3, 1)
// -> 2.0
``````
``````import gleam/list

list.fold([1, 2, 3], 10, subtract)
// -> 4
``````
``````3 |> subtract(2)
// -> 1
``````
``````3 |> subtract(2, _)
// -> -1
``````

## sum

</>
``pub fn sum(numbers: List(Int)) -> Int``

Sums a list of ints.

## Example

``````sum([1, 2, 3])
// -> 6
``````

## to_base16

</>
``pub fn to_base16(x: Int) -> String``

Prints a given int to a string using base-16.

## Examples

``````to_base16(48)
// -> "30"
``````

## to_base2

</>
``pub fn to_base2(x: Int) -> String``

Prints a given int to a string using base-2.

## Examples

``````to_base2(2)
// -> "10"
``````

## to_base36

</>
``pub fn to_base36(x: Int) -> String``

Prints a given int to a string using base-36.

## Examples

``````to_base36(48)
// -> "1C"
``````

## to_base8

</>
``pub fn to_base8(x: Int) -> String``

Prints a given int to a string using base-8.

## Examples

``````to_base8(15)
// -> "17"
``````

## to_base_string

</>
``````pub fn to_base_string(
x: Int,
base: Int,
) -> Result(String, InvalidBase)``````

Prints a given int to a string using the base number provided. Supports only bases 2 to 36, for values outside of which this function returns an `Error(InvalidBase)`. For common bases (2, 8, 16, 36), use the `to_baseN` functions.

## Examples

``````to_base_string(2, 2)
// -> Ok("10")
``````
``````to_base_string(48, 16)
// -> Ok("30")
``````
``````to_base_string(48, 36)
// -> Ok("1C")
``````
``````to_base_string(48, 1)
// -> Error(InvalidBase)
``````
``````to_base_string(48, 37)
// -> Error(InvalidBase)
``````

## to_float

</>
``pub fn to_float(x: Int) -> Float``

Takes an int and returns its value as a float.

## Examples

``````to_float(5)
// -> 5.0
``````
``````to_float(0)
// -> 0.0
``````
``````to_float(-3)
// -> -3.0
``````

## to_string

</>
``pub fn to_string(x: Int) -> String``

Prints a given int to a string.

## Examples

``````to_string(2)
// -> "2"
``````

## undigits

</>
``````pub fn undigits(
numbers: List(Int),
base: Int,
) -> Result(Int, InvalidBase)``````

Joins a list of digits into a single value. Returns an error if the base is less than 2 or if the list contains a digit greater than or equal to the specified base.

## Examples

``````undigits([2,3,4], 10)
// -> Ok(234)
``````
``````undigits([2,3,4], 1)
// -> Error(InvalidBase)
``````
``````undigits([2,3,4], 2)
// -> Error(InvalidBase)
``````