gleam/float

Functions for working with floats.

Division by zero

Gleam runs on the Erlang virtual machine, which does not follow the IEEE 754 standard for floating point arithmetic and does not have an Infinity value. 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.

Functions

absolute_value

</>

pub fn absolute_value(x: Float) -> Float

Returns the absolute value of the input as a Float.

Examples

absolute_value(-12.5)
// -> 12.5

absolute_value(10.2)
// -> 10.2

add

</>

pub fn add(a: Float, b: Float) -> Float

Adds two floats together.

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

Examples

add(1.0, 2.0)
// -> 3.0

import gleam/list

list.fold([1.0, 2.0, 3.0], 0.0, add)
// -> 6.0

3.0 |> add(2.0)
// -> 5.0

ceiling

</>

pub fn ceiling(x: Float) -> Float

Rounds the value to the next highest whole number as a Float.

Examples

ceiling(2.3)
// -> 3.0

clamp

</>

pub fn clamp(
  x: Float,
  min min_bound: Float,
  max max_bound: Float,
) -> Float

Restricts a Float between a lower and upper bound.

Examples

clamp(1.2, min: 1.4, max: 1.6)
// -> 1.4

compare

</>

pub fn compare(a: Float, with b: Float) -> Order

Compares two Floats, returning an Order: Lt for lower than, Eq for equals, or Gt for greater than.

Examples

compare(2.0, 2.3)
// -> Lt

To handle Floating Point Imprecision you may use loosely_compare instead.

divide

</>

pub fn divide(a: Float, by b: Float) -> Result(Float, Nil)

Returns division of the inputs as a Result.

Examples

divide(0.0, 1.0)
// -> Ok(0.0)

divide(1.0, 0.0)
// -> Error(Nil)

floor

</>

pub fn floor(x: Float) -> Float

Rounds the value to the next lowest whole number as a Float.

Examples

floor(2.3)
// -> 2.0

loosely_compare

</>

pub fn loosely_compare(
  a: Float,
  with b: Float,
  tolerating tolerance: Float,
) -> Order

Compares two Floats within a tolerance, returning an Order: Lt for lower than, Eq for equals, or Gt for greater than.

This function allows Float comparison while handling Floating Point Imprecision.

Notice: For Floats the tolerance won’t be exact: 5.3 - 5.0 is not exactly 0.3.

Examples

loosely_compare(5.0, with: 5.3, tolerating: 0.5)
// -> Eq

If you want to check only for equality you may use loosely_equals instead.

loosely_equals

</>

pub fn loosely_equals(
  a: Float,
  with b: Float,
  tolerating tolerance: Float,
) -> Bool

Checks for equality of two Floats within a tolerance, returning an Bool.

This function allows Float comparison while handling Floating Point Imprecision.

Notice: For Floats the tolerance won’t be exact: 5.3 - 5.0 is not exactly 0.3.

Examples

loosely_equals(5.0, with: 5.3, tolerating: 0.5)
// -> True

loosely_equals(5.0, with: 5.1, tolerating: 0.1)
// -> False

max

</>

pub fn max(a: Float, b: Float) -> Float

Compares two Floats, returning the larger of the two.

Examples

max(2.0, 2.3)
// -> 2.3

min

</>

pub fn min(a: Float, b: Float) -> Float

Compares two Floats, returning the smaller of the two.

Examples

min(2.0, 2.3)
// -> 2.0

modulo

</>

pub fn modulo(
  dividend: Float,
  by divisor: Float,
) -> Result(Float, Nil)

Computes the modulo of an float 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.

Examples

modulo(13.3, by: 3.3)
// -> Ok(0.1)

modulo(-13.3, by: 3.3)
// -> Ok(3.2)

modulo(13.3, by: -3.3)
// -> Ok(-3.2)

modulo(-13.3, by: -3.3)
// -> Ok(-0.1)

multiply

</>

pub fn multiply(a: Float, b: Float) -> Float

Multiplies two floats together.

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

Examples

multiply(2.0, 4.0)
// -> 8.0

import gleam/list

list.fold([2.0, 3.0, 4.0], 1.0, multiply)
// -> 24.0

3.0 |> multiply(2.0)
// -> 6.0

negate

</>

pub fn negate(x: Float) -> Float

Returns the negative of the value provided.

Examples

negate(1.0)
// -> -1.0

parse

</>

pub fn parse(string: String) -> Result(Float, Nil)

Attempts to parse a string as a Float, returning Error(Nil) if it was not possible.

Examples

parse("2.3")
// -> Ok(2.3)

parse("ABC")
// -> Error(Nil)

power

</>

pub fn power(
  base: Float,
  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.0, -1.0)
// -> Ok(0.5)

power(2.0, 2.0)
// -> Ok(4.0)

power(8.0, 1.5)
// -> Ok(22.627416997969522)

4.0 |> power(of: 2.0)
// -> Ok(16.0)

power(-1.0, 0.5)
// -> Error(Nil)

product

</>

pub fn product(numbers: List(Float)) -> Float

Multiplies a list of Floats and returns the product.

Example

product([2.5, 3.2, 4.2])
// -> 33.6

random

</>

pub fn random() -> Float

Generates a random float between the given zero (inclusive) and one (exclusive).

On Erlang this updates the random state in the process dictionary. See: https://www.erlang.org/doc/man/rand.html#uniform-0

Examples

random()
// -> 0.646355926896028

round

</>

pub fn round(x: Float) -> Int

Rounds the value to the nearest whole number as an Int.

Examples

round(2.3)
// -> 2

round(2.5)
// -> 3

square_root

</>

pub fn square_root(x: Float) -> Result(Float, Nil)

Returns the square root of the input as a Float.

Examples

square_root(4.0)
// -> Ok(2.0)

square_root(-16.0)
// -> Error(Nil)

subtract

</>

pub fn subtract(a: Float, b: Float) -> Float

Subtracts one float from another.

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

Examples

subtract(3.0, 1.0)
// -> 2.0

import gleam/list

list.fold([1.0, 2.0, 3.0], 10.0, subtract)
// -> 4.0

3.0 |> subtract(_, 2.0)
// -> 1.0

3.0 |> subtract(2.0, _)
// -> -1.0

sum

</>

pub fn sum(numbers: List(Float)) -> Float

Sums a list of Floats.

Example

sum([1.0, 2.2, 3.3])
// -> 6.5

to_precision

</>

pub fn to_precision(x: Float, precision: Int) -> Float

Converts the value to a given precision as a Float. The precision is the number of allowed decimal places. Negative precisions are allowed and force rounding to the nearest tenth, hundredth, thousandth etc.

Examples

to_precision(2.43434348473, precision: 2)
// -> 2.43

to_precision(547890.453444, precision: -3)
// -> 548000.0

to_string

</>

pub fn to_string(x: Float) -> String

Returns the string representation of the provided Float.

Examples

to_string(2.3)
// -> "2.3"

truncate

</>

pub fn truncate(x: Float) -> Int

Returns the value as an Int, truncating all decimal digits.

Examples

truncate(2.4343434847383438)
// -> 2