# Gleam IEEE Float
This Gleam library provides an `IEEEFloat` type that is compliant with the IEEE
754 standard for floating point arithmetic.
[](https://hex.pm/packages/ieee_float)
[](https://hexdocs.pm/ieee_float/)
## Background
Erlang's native float data type does not support infinity and NaN values, and
this library fills that gap when these values need to be able to be represented
and worked with.
On the JavaScript target, an `IEEEFloat` is simply a `number` because JavaScript
natively implements the IEEE 754 standard.
## Usage
Add this library to your project:
```sh
gleam add ieee_float
```
API documentation can be found at <https://hexdocs.pm/ieee_float/>.
The following code demonstrates commonly used functionality of this library.
```gleam
import ieee_float.{finite}
pub fn main() {
// Create finite values
let zero = finite(0.0)
let one = finite(1.0)
let two = finite(2.0)
let three = finite(3.0)
// Create infinity and NaN values
let positive_inf = ieee_float.positive_infinity()
let negative_inf = ieee_float.negative_infinity()
let nan = ieee_float.nan()
// Check whether a value is finite or NaN
let assert False = ieee_float.is_finite(positive_inf)
let assert True = ieee_float.is_nan(nan)
// Convert to a finite value of type `Float`. If the IEEE float is not
// finite then an error is returned.
let assert Ok(1.0) = ieee_float.to_finite(one)
let assert Error(Nil) = ieee_float.to_finite(positive_inf)
// Convert a value to raw bytes
let assert <<0x3F, 0x80, 0x00, 0x00>> = ieee_float.to_bytes_32_be(one)
// Create a value from raw bytes
let assert True =
ieee_float.from_bytes_32_be(<<0x3F, 0x80, 0x00, 0x00>>) == one
// Perform math operations
let assert True = ieee_float.add(two, three) == finite(5.0)
let assert True = ieee_float.divide(one, two) == finite(0.5)
let assert True = ieee_float.multiply(two, three) == finite(6.0)
let assert True = ieee_float.subtract(three, one) == finite(2.0)
// Perform math operations not supported by Erlang floats
let assert True = ieee_float.add(one, positive_inf) == positive_inf
let assert True =
ieee_float.add(positive_inf, negative_inf) |> ieee_float.is_nan
let assert True = ieee_float.multiply(positive_inf, two) == positive_inf
let assert True =
ieee_float.multiply(negative_inf, positive_inf) == negative_inf
let assert True = ieee_float.divide(two, zero) == positive_inf
let assert True =
ieee_float.divide(positive_inf, positive_inf) |> ieee_float.is_nan
}
```
## License
This library is published under the MIT license, a copy of which is included.
