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(0.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 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)
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"