gleam_stdlib - v0.70.0

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.

Values

absolute_value

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

Returns the absolute value of the input.

Examples

assert absolute_value(-12) == 12

assert absolute_value(10) == 10

add

</> 
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

assert add(1, 2) == 3

import gleam/list
assert list.fold([1, 2, 3], 0, add) == 6

assert 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

assert base_parse("10", 2) == Ok(2)

assert base_parse("30", 16) == Ok(48)

assert base_parse("1C", 36) == Ok(48)

assert base_parse("48", 1) == Error(Nil)

assert base_parse("48", 37) == Error(Nil)

bitwise_and

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

Calculates the bitwise AND of its arguments.

Most the time you should use the bit array syntaxes instead of manipulating bits as ints with bitwise functions.

Target specific behaviour

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. If you need to avoid the overhead of big-ints on JavaScript use bit arrays or another package that provides faster bitwise operations.

bitwise_exclusive_or

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

Calculates the bitwise XOR of its arguments.

Most the time you should use the bit array syntaxes instead of manipulating bits as ints with bitwise functions.

Target specific behaviour

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. If you need to avoid the overhead of big-ints on JavaScript use bit arrays or another package that provides faster bitwise operations.

bitwise_not

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

Calculates the bitwise NOT of its argument.

Most the time you should use the bit array syntaxes instead of manipulating bits as ints with bitwise functions.

Target specific behaviour

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. If you need to avoid the overhead of big-ints on JavaScript use bit arrays or another package that provides faster bitwise operations.

bitwise_or

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

Calculates the bitwise OR of its arguments.

Most the time you should use the bit array syntaxes instead of manipulating bits as ints with bitwise functions.

Target specific behaviour

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. If you need to avoid the overhead of big-ints on JavaScript use bit arrays or another package that provides faster bitwise operations.

bitwise_shift_left

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

Calculates the result of an arithmetic left bitshift.

Most the time you should use the bit array syntaxes instead of manipulating bits as ints with bitwise functions.

Target specific behaviour

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. If you need to avoid the overhead of big-ints on JavaScript use bit arrays or another package that provides faster bitwise operations.

bitwise_shift_right

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

Calculates the result of an arithmetic right bitshift.

Most the time you should use the bit array syntaxes instead of manipulating bits as ints with bitwise functions.

Target specific behaviour

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. If you need to avoid the overhead of big-ints on JavaScript use bit arrays or another package that provides faster bitwise operations.

clamp

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

Restricts an int between two bounds.

Note: If the min argument is larger than the max argument then they will be swapped, so the minimum bound is always lower than the maximum bound.

Examples

assert clamp(40, min: 50, max: 60) == 50

assert clamp(40, min: 50, max: 30) == 40

compare

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

Compares two ints, returning an order.

Examples

assert compare(2, 3) == Lt

assert compare(4, 3) == Gt

assert compare(3, 3) == Eq

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

assert divide(0, 1) == Ok(0)

assert divide(1, 0) == Error(Nil)

assert divide(5, 2) == Ok(2)

assert 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

assert floor_divide(1, 0) == Error(Nil)

assert floor_divide(5, 2) == Ok(2)

assert floor_divide(6, -4) == Ok(-2)

assert floor_divide(-99, 2) == Ok(-50)

is_even

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

Returns whether the value provided is even.

Examples

assert is_even(2)

assert !is_even(3)

is_odd

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

Returns whether the value provided is odd.

Examples

assert is_odd(3)

assert !is_odd(2)

max

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

Compares two ints, returning the larger of the two.

Examples

assert max(2, 3) == 3

min

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

Compares two ints, returning the smaller of the two.

Examples

assert 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.

Note that this is different from int.remainder and % in that the computed value will always have the same sign as the divisor.

Examples

assert modulo(3, 2) == Ok(1)

assert modulo(1, 0) == Error(Nil)

assert modulo(10, -1) == Ok(0)

assert modulo(13, by: 3) == Ok(1)

assert modulo(-13, by: 3) == Ok(2)

assert 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

assert multiply(2, 4) == 8

import gleam/list

assert list.fold([2, 3, 4], 1, multiply) == 24

assert 3 |> multiply(2) == 6

negate

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

Returns the negative of the value provided.

Examples

assert negate(1) == -1

parse

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

Parses a given string as an int if possible.

Examples

assert parse("2") == Ok(2)

assert parse("ABC") == Error(Nil)

power

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

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

Examples

assert power(2, -1.0) == Ok(0.5)

assert power(2, 2.0) == Ok(4.0)

assert power(8, 1.5) == Ok(22.627416997969522)

assert 4 |> power(of: 2.0) == Ok(16.0)

assert power(-1, 0.5) == Error(Nil)

product

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

Multiplies a list of ints and returns the product.

Example

assert 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

range

</> 
pub fn range(
  from start: Int,
  to stop: Int,
  with acc: acc,
  run reducer: fn(acc, Int) -> acc,
) -> acc

Run a function for each int between ints from and to.

from is inclusive, and to is exclusive.

Examples

assert
  range(from: 0, to: 3, with: "", run: fn(acc, i) {
    acc <> to_string(i)
  })
  == "012"

assert range(from: 1, to: -2, with: [], run: list.prepend) == [-1, 0, 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 of the time you will want to use the % operator instead of this function.

Examples

assert remainder(3, 2) == Ok(1)

assert remainder(1, 0) == Error(Nil)

assert remainder(10, -1) == Ok(0)

assert remainder(13, by: 3) == Ok(1)

assert remainder(-13, by: 3) == Ok(-1)

assert remainder(13, by: -3) == Ok(1)

assert 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

assert square_root(4) == Ok(2.0)

assert 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

assert subtract(3, 1) == 2

import gleam/list

assert list.fold([1, 2, 3], 10, subtract) == 4

assert 3 |> subtract(2) == 1

assert 3 |> subtract(2, _) == -1

sum

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

Sums a list of ints.

Example

assert 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

assert to_base16(48) == "30"

to_base2

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

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

Examples

assert to_base2(2) == "10"

to_base36

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

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

Examples

assert to_base36(48) == "1C"

to_base8

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

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

Examples

assert to_base8(15) == "17"

to_base_string

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

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(Nil). For common bases (2, 8, 16, 36), use the to_baseN functions.

Examples

assert to_base_string(2, 2) == Ok("10")

assert to_base_string(48, 16) == Ok("30")

assert to_base_string(48, 36) == Ok("1C")

assert to_base_string(48, 1) == Error(Nil)

assert to_base_string(48, 37) == Error(Nil)

to_float

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

Takes an int and returns its value as a float.

Examples

assert to_float(5) == 5.0

assert to_float(0) == 0.0

assert to_float(-3) == -3.0

to_string

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

Prints a given int to a string.

Examples

assert to_string(2) == "2"
✨ Search Document