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
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
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
pub fn ceiling(x: Float) -> Float
Rounds the value to the next highest whole number as a Float
.
Examples
> ceiling(2.3)
3.0
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
pub fn compare(a: Float, with b: Float) -> Order
Compares two Float
s, 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.
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)
pub fn floor(x: Float) -> Float
Rounds the value to the next lowest whole number as a Float
.
Examples
> floor(2.3)
2.0
pub fn loosely_compare(
a: Float,
with b: Float,
tolerating tolerance: Float,
) -> Order
Compares two Float
s 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 Float
s 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.
pub fn loosely_equals(
a: Float,
with b: Float,
tolerating tolerance: Float,
) -> Bool
Checks for equality of two Float
s within a tolerance,
returning an Bool
.
This function allows Float comparison while handling Floating Point Imprecision.
Notice: For Float
s 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
pub fn max(a: Float, b: Float) -> Float
Compares two Float
s, returning the larger of the two.
Examples
> max(2.0, 2.3)
2.3
pub fn min(a: Float, b: Float) -> Float
Compares two Float
s, returning the smaller of the two.
Examples
> min(2.0, 2.3)
2.0
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
pub fn negate(x: Float) -> Float
Returns the negative of the value provided.
Examples
> negate(1.0)
-1.0
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)
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)
pub fn product(numbers: List(Float)) -> Float
Multiplies a list of Float
s and returns the product.
Example
> product([2.5, 3.2, 4.2])
33.6
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
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
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)
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
pub fn sum(numbers: List(Float)) -> Float
Sums a list of Float
s.
Example
> sum([1.0, 2.2, 3.3])
6.5
pub fn to_string(x: Float) -> String
Returns the string representation of the provided Float
.
Examples
> to_string(2.3)
"2.3"