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
Error value when trying to operate with a base out of the allowed range.
pub type InvalidBase {
InvalidBase
}
Constructors
-
InvalidBase
Functions
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
Adds two integers together.
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
list.fold([1, 2, 3], 0, add)
// -> 6
3 |> add(2)
// -> 5
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)
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.
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.
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.
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.
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.
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.
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
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
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)
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)
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)
pub fn is_even(x: Int) -> Bool
Returns whether the value provided is even.
Examples
is_even(2)
// -> True
is_even(3)
// -> False
pub fn is_odd(x: Int) -> Bool
Returns whether the value provided is odd.
Examples
is_odd(3)
// -> True
is_odd(2)
// -> False
pub fn max(a: Int, b: Int) -> Int
Compares two ints, returning the larger of the two.
Examples
max(2, 3)
// -> 3
pub fn min(a: Int, b: Int) -> Int
Compares two ints, returning the smaller of the two.
Examples
min(2, 3)
// -> 2
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)
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
pub fn negate(x: Int) -> Int
Returns the negative of the value provided.
Examples
negate(1)
// -> -1
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)
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)
pub fn product(numbers: List(Int)) -> Int
Multiplies a list of ints and returns the product.
Example
product([2, 3, 4])
// -> 24
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
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)
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)
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
pub fn to_base16(x: Int) -> String
Prints a given int to a string using base-16.
Examples
to_base16(48)
// -> "30"
pub fn to_base2(x: Int) -> String
Prints a given int to a string using base-2.
Examples
to_base2(2)
// -> "10"
pub fn to_base36(x: Int) -> String
Prints a given int to a string using base-36.
Examples
to_base36(48)
// -> "1C"
pub fn to_base8(x: Int) -> String
Prints a given int to a string using base-8.
Examples
to_base8(15)
// -> "17"
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)
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
pub fn to_string(x: Int) -> String
Prints a given int to a string.
Examples
to_string(2)
// -> "2"
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)