# 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
``````

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

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

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

## 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 `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.

## loosely_equals

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

## max

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

## min

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

## 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 `Float`s 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 `Float`s.

## 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
``````