# gleam_community/maths/arithmetics

Arithmetics: A module containing a collection of fundamental mathematical functions relating to simple arithmetics (addition, subtraction, multiplication, etc.), but also number theory.

# Functions

## divisors

</>
pub fn divisors(n: Int) -> List(Int)

The function returns all the positive divisors of an integer, including the number iteself.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example() {
arithmetics.divisors(4)
|> should.equal([1, 2, 4])

arithmetics.divisors(6)
|> should.equal([1, 2, 3, 6])

arithmetics.proper_divisors(13)
|> should.equal([1, 13])
}


## float_cumulative_sum

</>
pub fn float_cumulative_sum(arr: List(Float)) -> List(Float)

Calculcate the cumulative sum of the elements in a list:

$v_j = \sum_{i=1}^j x_i \;\; \forall j = 1,\dots, n$

In the formula, $$v_j$$ is the $$j$$’th element in the cumulative sum of $$n$$ elements. That is, $$n$$ is the length of the list and $$x_i \in \mathbb{R}$$ is the value in the input list indexed by $$i$$. The value $$v_j$$ is thus the sum of the $$1$$ to $$j$$ first elements in the given list.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
[]
|> arithmetics.float_cumulative_sum()
|> should.equal([])

// Valid input returns a result
[1.0, 2.0, 3.0]
|> arithmetics.float_cumulative_sum()
|> should.equal([1.0, 3.0, 6.0])
}


## float_cumumlative_product

</>
pub fn float_cumumlative_product(arr: List(Float)) -> List(Float)

Calculcate the cumulative product of the elements in a list:

$v_j = \prod_{i=1}^j x_i \;\; \forall j = 1,\dots, n$

In the formula, $$v_j$$ is the $$j$$’th element in the cumulative product of $$n$$ elements. That is, $$n$$ is the length of the list and $$x_i \in \mathbb{R}$$ is the value in the input list indexed by $$i$$. The value $$v_j$$ is thus the sum of the $$1$$ to $$j$$ first elements in the given list.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
// An empty list returns an error
[]
|> arithmetics.float_cumulative_product()
|> should.equal([])

// Valid input returns a result
[1.0, 2.0, 3.0]
|> arithmetics.float_cumulative_product()
|> should.equal([1.0, 2.0, 6.0])
}


## float_product

</>
pub fn float_product(arr: List(Float)) -> Float

Calculcate the product of the elements in a list:

$\prod_{i=1}^n x_i$

In the formula, $$n$$ is the length of the list and $$x_i \in \mathbb{R}$$ is the value in the input list indexed by $$i$$.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
// An empty list returns 0.0
[]
|> arithmetics.float_product()
|> should.equal(0.0)

// Valid input returns a result
[1.0, 2.0, 3.0]
|> arithmetics.float_product()
|> should.equal(6.0)
}


## float_sum

</>
pub fn float_sum(arr: List(Float)) -> Float

Calculcate the sum of the elements in a list:

$\sum_{i=1}^n x_i$

In the formula, $$n$$ is the length of the list and $$x_i \in \mathbb{R}$$ is the value in the input list indexed by $$i$$.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
// An empty list returns an error
[]
|> arithmetics.float_sum()
|> should.equal(0.0)

// Valid input returns a result
[1.0, 2.0, 3.0]
|> arithmetics.float_sum()
|> should.equal(6.0)
}


## gcd

</>
pub fn gcd(x: Int, y: Int) -> Int

The function calculates the greatest common multiple of two integers $$x, y \in \mathbb{Z}$$. The greatest common multiple is the largest positive integer that is divisible by both $$x$$ and $$y$$.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example() {
arithmetics.lcm(1, 1)
|> should.equal(1)

arithmetics.lcm(100, 10)
|> should.equal(10)

arithmetics.gcd(-36, -17)
|> should.equal(1)
}


## int_cumulative_product

</>
pub fn int_cumulative_product(arr: List(Int)) -> List(Int)

Calculcate the cumulative product of the elements in a list:

$v_j = \prod_{i=1}^j x_i \;\; \forall j = 1,\dots, n$

In the formula, $$v_j$$ is the $$j$$’th element in the cumulative product of $$n$$ elements. That is, $$n$$ is the length of the list and $$x_i \in \mathbb{Z}$$ is the value in the input list indexed by $$i$$. The value $$v_j$$ is thus the product of the $$1$$ to $$j$$ first elements in the given list.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
// An empty list returns an error
[]
|> arithmetics.int_cumulative_product()
|> should.equal([])

// Valid input returns a result
[1, 2, 3]
|> arithmetics.int_cumulative_product()
|> should.equal([1, 2, 6])
}


## int_cumulative_sum

</>
pub fn int_cumulative_sum(arr: List(Int)) -> List(Int)

Calculcate the cumulative sum of the elements in a list:

$v_j = \sum_{i=1}^j x_i \;\; \forall j = 1,\dots, n$

In the formula, $$v_j$$ is the $$j$$’th element in the cumulative sum of $$n$$ elements. That is, $$n$$ is the length of the list and $$x_i \in \mathbb{Z}$$ is the value in the input list indexed by $$i$$. The value $$v_j$$ is thus the sum of the $$1$$ to $$j$$ first elements in the given list.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
[]
|> arithmetics.int_cumulative_sum()
|> should.equal([])

// Valid input returns a result
[1, 2, 3]
|> arithmetics.int_cumulative_sum()
|> should.equal([1, 3, 6])
}


## int_euclidean_modulo

</>
pub fn int_euclidean_modulo(x: Int, y: Int) -> Int

Given two integers, $$x$$ (dividend) and $$y$$ (divisor), the Euclidean modulo of $$x$$ by $$y$$, denoted as $$x \mod y$$, is the remainder $$r$$ of the division of $$x$$ by $$y$$, such that:

$x = q \cdot y + r \quad \text{and} \quad 0 \leq r < |y|,$

where $$q$$ is an integer that represents the quotient of the division.

The Euclidean modulo function of two numbers, is the remainder operation most commonly utilized in mathematics. This differs from the standard truncating modulo operation frequently employed in programming via the % operator. Unlike the % operator, which may return negative results depending on the divisor’s sign, the Euclidean modulo function is designed to always yield a positive outcome, ensuring consistency with mathematical conventions.

Note that like the Gleam division operator / this will return 0 if one of the arguments is 0.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example() {
arithmetics.euclidean_modulo(15, 4)
|> should.equal(3)

arithmetics.euclidean_modulo(-3, -2)
|> should.equal(1)

arithmetics.euclidean_modulo(5, 0)
|> should.equal(0)
}


## int_product

</>
pub fn int_product(arr: List(Int)) -> Int

Calculcate the product of the elements in a list:

$\prod_{i=1}^n x_i$

In the formula, $$n$$ is the length of the list and $$x_i \in \mathbb{Z}$$ is the value in the input list indexed by $$i$$.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
// An empty list returns 0
[]
|> arithmetics.int_product()
|> should.equal(0)

// Valid input returns a result
[1, 2, 3]
|> arithmetics.int_product()
|> should.equal(6)
}


## int_sum

</>
pub fn int_sum(arr: List(Int)) -> Int

Calculcate the sum of the elements in a list:

$\sum_{i=1}^n x_i$

In the formula, $$n$$ is the length of the list and $$x_i \in \mathbb{Z}$$ is the value in the input list indexed by $$i$$.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example () {
// An empty list returns 0
[]
|> arithmetics.int_sum()
|> should.equal(0)

// Valid input returns a result
[1, 2, 3]
|> arithmetics.int_sum()
|> should.equal(6)
}


## lcm

</>
pub fn lcm(x: Int, y: Int) -> Int

The function calculates the least common multiple of two integers $$x, y \in \mathbb{Z}$$. The least common multiple is the smallest positive integer that has both $$x$$ and $$y$$ as factors.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example() {
arithmetics.lcm(1, 1)
|> should.equal(1)

arithmetics.lcm(100, 10)
|> should.equal(100)

arithmetics.lcm(-36, -17)
|> should.equal(612)
}


## proper_divisors

</>
pub fn proper_divisors(n: Int) -> List(Int)

The function returns all the positive divisors of an integer, excluding the number iteself.

Example:
import gleeunit/should
import gleam_community/maths/arithmetics

pub fn example() {
arithmetics.proper_divisors(4)
|> should.equal([1, 2])

arithmetics.proper_divisors(6)
|> should.equal([1, 2, 3])

arithmetics.proper_divisors(13)
|> should.equal([1])
}