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(1.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

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(min: Float, max: Float) -> Float

Generates a random float between the given minimum and maximum values.

Examples

> random(1.0, 5.0)
2.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_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