# gleam_community/maths/elementary

Elementary: A module containing a comprehensive set of foundational mathematical functions and constants.

• Trigonometric and hyperbolic functions
• Powers, logs and roots
• Mathematical constants

# Functions

## acos

</>
pub fn acos(x: Float) -> Result(Float, String)

The inverse cosine function:

$\forall x \in [-1, 1], \; \cos^{-1}{(x)} = y \in [0, \pi ]$

The function takes a number $$x$$ in its domain $$[-1, 1]$$ as input and returns a numeric value $$y$$ that lies in the range $$[0, \pi ]$$ (an angle in radians). If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.acos(1.0)
|> should.equal(Ok(0.0))

elementary.acos(1.1)
|> should.be_error()

elementary.acos(-1.1)
|> should.be_error()
}


## acosh

</>
pub fn acosh(x: Float) -> Result(Float, String)

The inverse hyperbolic cosine function:

$\forall x \in [1, +\infty), \; \cosh^{-1}{(x)} = y \in [0, +\infty)$

The function takes a number $$x$$ in its domain $$[1, +\infty)$$ as input and returns a numeric value $$y$$ that lies in the range $$[0, +\infty)$$ (an angle in radians). If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.acosh(1.0)
|> should.equal(Ok(0.0))

elementary.acosh(0.0)
|> should.be_error()
}


## asin

</>
pub fn asin(x: Float) -> Result(Float, String)

The inverse sine function:

$\forall x \in [-1, 1], \; \sin^{-1}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$[-1, 1]$$ as input and returns a numeric value $$y$$ that lies in the range $$[-\frac{\pi}{2}, \frac{\pi}{2}]$$ (an angle in radians). If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.asin(0.0)
|> should.equal(Ok(0.0))

elementary.asin(1.1)
|> should.be_error()

elementary.asin(-1.1)
|> should.be_error()
}


## asinh

</>
pub fn asinh(x: Float) -> Float

The inverse hyperbolic sine function:

$\forall x \in (-\infty, \infty), \; \sinh^{-1}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(-\infty, +\infty)$$ as input and returns a numeric value $$y$$ that lies in the range $$(-\infty, +\infty)$$ (an angle in radians).

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.asinh(0.0)
|> should.equal(0.0)
}


## atan

</>
pub fn atan(x: Float) -> Float

The inverse tangent function:

$\forall x \in (-\infty, \infty), \; \tan^{-1}{(x)} = y \in [-\frac{\pi}{2}, \frac{\pi}{2}]$

The function takes a number $$x$$ in its domain $$(-\infty, +\infty)$$ as input and returns a numeric value $$y$$ that lies in the range $$[-\frac{\pi}{2}, \frac{\pi}{2}]$$ (an angle in radians).

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.atan(0.0)
|> should.equal(0.0)
}


## atan2

</>
pub fn atan2(y: Float, x: Float) -> Float

The inverse 2-argument tangent function:

$\text{atan2}(y, x) = \begin{cases} \tan^{-1}(\frac y x) &\text{if } x > 0, \\ \tan^{-1}(\frac y x) + \pi &\text{if } x < 0 \text{ and } y \ge 0, \\ \tan^{-1}(\frac y x) - \pi &\text{if } x < 0 \text{ and } y < 0, \\ +\frac{\pi}{2} &\text{if } x = 0 \text{ and } y > 0, \\ -\frac{\pi}{2} &\text{if } x = 0 \text{ and } y < 0, \\ \text{undefined} &\text{if } x = 0 \text{ and } y = 0. \end{cases}$

The function returns the angle in radians from the x-axis to the line containing the origin $$(0, 0)$$ and a point given as input with coordinates $$(x, y)$$. The numeric value returned by $$\text{atan2}(y, x)$$ is in the range $$[-\pi, \pi]$$.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.atan2(0.0, 0.0)
|> should.equal(0.0)
}


## atanh

</>
pub fn atanh(x: Float) -> Result(Float, String)

The inverse hyperbolic tangent function:

$\forall x \in (-1, 1), \; \tanh^{-1}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(-1, 1)$$ as input and returns a numeric value $$y$$ that lies in the range $$(-\infty, \infty)$$ (an angle in radians). If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.atanh(0.0)
|> should.equal(Ok(0.0))

elementary.atanh(1.0)
|> should.be_error()

elementary.atanh(-1.0)
|> should.be_error()
}


## cos

</>
pub fn cos(x: Float) -> Float

The cosine function:

$\forall x \in (-\infty, +\infty), \; \cos{(x)} = y \in [-1, 1]$

The function takes a number $$x$$ in its domain $$(-\infty, \infty)$$ (an angle in radians) as input and returns a numeric value $$y$$ that lies in the range $$[-1, 1]$$.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.cos(0.0)
|> should.equal(1.0)

elementary.cos(elementary.pi())
|> should.equal(-1.0)
}


## cosh

</>
pub fn cosh(x: Float) -> Float

The hyperbolic cosine function:

$\forall x \in (-\infty, \infty), \; \cosh{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(-\infty, \infty)$$ as input (an angle in radians) and returns a numeric value $$y$$ that lies in the range $$(-\infty, \infty)$$. If the input value is too large an overflow error might occur.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.cosh(0.0)
|> should.equal(0.0)
}


## cube_root

</>
pub fn cube_root(x: Float) -> Result(Float, String)

The cube root function: $$y = \sqrt[3]{x} = x^{\frac{1}{3}}$$.

Note that the function is not defined if:

1. The input is negative ($$x < 0$$). An error will be returned as an imaginary number will otherwise have to be returned.
Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.cube_root(1.0)
|> should.equal(Ok(1.0))

elementary.cube_root(27.0)
|> should.equal(Ok(3.0))

elementary.cube_root(-1.0)
|> should.be_error()
}


## e

</>
pub fn e() -> Float

Euler’s number $$e \approx 2.71828\dots$$.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
// Test that the constant is approximately equal to 2.7128...
elementary.e()
|> elementary.is_close(2.7128, 0.0, 0.000001)
|> should.be_true()
}


## exponential

</>
pub fn exponential(x: Float) -> Float

The exponential function:

$\forall x \in (-\infty, \infty), \; e^{(x)} = y \in (0, +\infty)$

$$e \approx 2.71828\dots$$ is Eulers’ number.

Note: If the input value $$x$$ is too large an overflow error might occur.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.exponential(0.0)
|> should.equal(1.0)
}


## logarithm

</>
pub fn logarithm(x: Float, base: Option(Float)) -> Result(
Float,
String,
)

The base $$b$$ logarithm function (computed through the “change of base” formula):

$\forall x \in (0, \infty) \textnormal{ and } b > 1, \; \log_{b}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(0, \infty)$$ and a base $$b > 1$$ as input and returns a numeric value $$y$$ that lies in the range $$(-\infty, \infty)$$. If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam/option
import gleam_community/maths/elementary

pub fn example () {
elementary.logarithm(1.0, option.Some(10.0))
|> should.equal(Ok(0.0))

elementary.logarithm(elementary.e(), option.Some(elementary.e()))
|> should.equal(Ok(1.0))

elementary.logarithm(-1.0, option.Some(2.0))
|> should.be_error()
}


## logarithm_10

</>
pub fn logarithm_10(x: Float) -> Result(Float, String)

The base-10 logarithm function:

$\forall x \in (0, \infty), \; \log_{10}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(0, \infty)$$ as input and returns a numeric value $$y$$ that lies in the range $$(-\infty, \infty)$$. If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example () {
elementary.logarithm_10(1.0)
|> should.equal(Ok(0.0))

elementary.logarithm_10(10.0)
|> should.equal(Ok(1.0))

elementary.logarithm_10(-1.0)
|> should.be_error()
}


## logarithm_2

</>
pub fn logarithm_2(x: Float) -> Result(Float, String)

The The base-2 logarithm function:

$\forall x \in (0, \infty), \; \log_{2}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(0, \infty)$$ as input and returns a numeric value $$y$$ that lies in the range $$(-\infty, \infty)$$. If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example () {
elementary.logarithm_2(1.0)
|> should.equal(Ok(0.0))

elementary.logarithm_2(2.0)
|> should.equal(Ok(1.0))

elementary.logarithm_2(-1.0)
|> should.be_error()
}


## natural_logarithm

</>
pub fn natural_logarithm(x: Float) -> Result(Float, String)

The natural logarithm function:

$\forall x \in (0, \infty), \; \log_{e}{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(0, \infty)$$ as input and returns a numeric value $$y$$ that lies in the range $$(-\infty, \infty)$$. If the input value is outside the domain of the function an error is returned.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example () {
elementary.natural_logarithm(1.0)
|> should.equal(Ok(0.0))

elementary.natural_logarithm(elementary.e())
|> should.equal(Ok(1.0))

elementary.natural_logarithm(-1.0)
|> should.be_error()
}


## nth_root

</>
pub fn nth_root(x: Float, n: Int) -> Result(Float, String)

The $$n$$’th root function: $$y = \sqrt[n]{x} = x^{\frac{1}{n}}$$.

Note that the function is not defined if:

1. The input is negative ($$x < 0$$). An error will be returned as an imaginary number will otherwise have to be returned.
Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.nth_root(1.0, 2)
|> should.equal(Ok(1.0))

elementary.nth_root(27.0, 3)
|> should.equal(Ok(3.0))

elementary.nth_root(256.0, 4)
|> should.equal(Ok(4.0))

elementary.nth_root(-1.0, 2)
|> should.be_error()
}


## pi

</>
pub fn pi() -> Float

The mathematical constant pi: $$\pi \approx 3.1415\dots$$

## power

</>
pub fn power(x: Float, y: Float) -> Result(Float, String)

The exponentiation function: $$y = x^{a}$$.

Note that the function is not defined if:

1. The base is negative ($$x < 0$$) and the exponent is fractional ($$a = \frac{n}{m}$$ is an irrreducible fraction). An error will be returned as an imaginary number will otherwise have to be returned.
2. The base is zero ($$x = 0$$) and the exponent is negative ($$a < 0$$) then the expression is equivalent to the exponent $$y$$ divided by $$0$$ and an error will have to be returned as the expression is otherwise undefined.
Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.power(2., -1.)
|> should.equal(Ok(0.5))

elementary.power(2., 2.)
|> should.equal(Ok(4.0))

elementary.power(-1., 0.5)
|> should.be_error()
}


## sin

</>
pub fn sin(x: Float) -> Float

The sine function:

$\forall x \in (-\infty, +\infty), \; \sin{(x)} = y \in [-1, 1]$

The function takes a number $$x$$ in its domain $$(-\infty, \infty)$$ (an angle in radians) as input and returns a numeric value $$y$$ that lies in the range $$[-1, 1]$$.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.sin(0.0)
|> should.equal(0.0)

elementary.sin(0.5 *. elementary.pi())
|> should.equal(1.0)
}


## sinh

</>
pub fn sinh(x: Float) -> Float

The hyperbolic sine function:

$\forall x \in (-\infty, +\infty), \; \sinh{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(-\infty, +\infty)$$ as input (an angle in radians) and returns a numeric value $$y$$ that lies in the range $$(-\infty, +\infty)$$. If the input value is too large an overflow error might occur.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.sinh(0.0)
|> should.equal(0.0)
}


## square_root

</>
pub fn square_root(x: Float) -> Result(Float, String)

The square root function: $$y = \sqrt[2]{x} = x^{\frac{1}{2}}$$.

Note that the function is not defined if:

1. The input is negative ($$x < 0$$). An error will be returned as an imaginary number will otherwise have to be returned.
Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.square_root(1.0)
|> should.equal(Ok(1.0))

elementary.square_root(4.0)
|> should.equal(Ok(2.0))

elementary.square_root(-1.0)
|> should.be_error()
}


## tan

</>
pub fn tan(x: Float) -> Float

The tangent function:

$\forall x \in (-\infty, +\infty), \; \tan{(x)} = y \in (-\infty, +\infty)$

The function takes a number $$x$$ in its domain $$(-\infty, +\infty)$$ as input (an angle in radians) and returns a numeric value $$y$$ that lies in the range $$(-\infty, +\infty)$$.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example() {
elementary.tan(0.0)
|> should.equal(0.0)
}


## tanh

</>
pub fn tanh(x: Float) -> Float

The hyperbolic tangent function:

$\forall x \in (-\infty, \infty), \; \tanh{(x)} = y \in [-1, 1]$

The function takes a number $$x$$ in its domain $$(-\infty, \infty)$$ as input (an angle in radians) and returns a numeric value $$y$$ that lies in the range $$[-1, 1]$$.

Example
 import gleeunit/should
import gleam_community/maths/elementary

pub fn example () {
elementary.tanh(0.0)
|> should.equal(0.0)

elementary.tanh(25.0)
|> should.equal(1.0)

elementary.tanh(-25.0)
|> should.equal(-1.0)
}


## tau

</>
pub fn tau() -> Float

The mathematical constant tau: $$\tau = 2 \cdot \pi \approx 6.283\dots$$