gleam_community_maths - v1.1.0

gleam_community/maths/piecewise

Piecewise: A module containing functions that have different definitions depending on conditions or intervals of their domain.

Types

RoundingMode

</> 
pub type RoundingMode {
  RoundNearest
  RoundTiesAway
  RoundTiesUp
  RoundToZero
  RoundDown
  RoundUp
}

Constructors 

  • RoundNearest
  • RoundTiesAway
  • RoundTiesUp
  • RoundToZero
  • RoundDown
  • RoundUp

Functions

arg_maximum

</> 
pub fn arg_maximum(
  arr: List(a),
  compare: fn(a, a) -> Order,
) -> Result(List(Int), String)

Returns the indices of the maximum values in a given list.

Example: 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example () {
  // An empty lists returns an error
  []
  |> piecewise.arg_maximum(float.compare)
  |> should.be_error()

  // Valid input returns a result
  [4.0, 4.0, 3.0, 2.0, 1.0]
  |> piecewise.arg_maximum(float.compare)
  |> should.equal(Ok([0, 1]))
}

arg_minimum

</> 
pub fn arg_minimum(
  arr: List(a),
  compare: fn(a, a) -> Order,
) -> Result(List(Int), String)

Returns the indices of the minimum values in a given list.

Example: 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example () {
  // An empty lists returns an error
  []
  |> piecewise.arg_minimum(float.compare)
  |> should.be_error()

  // Valid input returns a result
  [4.0, 4.0, 3.0, 2.0, 1.0]
  |> piecewise.arg_minimum(float.compare)
  |> should.equal(Ok([4]))
}

ceiling

</> 
pub fn ceiling(
  x: Float,
  digits: Option(Int),
) -> Result(Float, String)

The ceiling function rounds a given input value $$x \in \mathbb{R}$$ to the nearest integer value (at the specified digit) that is larger than or equal to the input $$x$$.

Note: The ceiling function is used as an alias for the rounding function round with rounding mode RoundUp.

Details

For example, $$12.0654$$ is rounded to:

  • $$13.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.1$$ for 1 digit after the decimal point (digits = 1)
  • $$12.07$$ for 2 digits after the decimal point (digits = 2)
  • $$12.066$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point. For example, $$12.0654$$ is rounded to:

  • $$20.0$$ for 1 digit places before the decimal point (digit = -1)
  • $$100.0$$ for 2 digits before the decimal point (digits = -2)
  • $$1000.0$$ for 3 digits before the decimal point (digits = -3)
Example 
import gleeunit/should
import gleam/option
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.ceiling(12.0654, option.Some(1))
  |> should.equal(Ok(12.1))

  piecewise.ceiling(12.0654, option.Some(2))
  |> should.equal(Ok(12.07))

  piecewise.ceiling(12.0654, option.Some(3))
  |> should.equal(Ok(12.066))
}

extrema

</> 
pub fn extrema(
  arr: List(a),
  compare: fn(a, a) -> Order,
) -> Result(#(a, a), String)

Returns a tuple consisting of the minimum and maximum values of a given list.

Example: 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example () {
  // An empty lists returns an error
  []
  |> piecewise.extrema(float.compare)
  |> should.be_error()

  // Valid input returns a result
  [4.0, 4.0, 3.0, 2.0, 1.0]
  |> piecewise.extrema(float.compare)
  |> should.equal(Ok(#(1.0, 4.0)))
}

float_absolute_difference

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

The absolute difference:

\[ \forall x, y \in \mathbb{R}, \; |x - y| \in \mathbb{R}_{+}. \]

The function takes two inputs $$x$$ and $$y$$ and returns a positive float value which is the the absolute difference of the inputs.

Example 
import gleeunit/should
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.float_absolute_difference(-10.0, 10.0)
  |> should.equal(20.0)

  piecewise.float_absolute_difference(0.0, -2.0)
  |> should.equal(2.0)
}

float_absolute_value

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

The absolute value:

\[ \forall x, y \in \mathbb{R}, \; |x| \in \mathbb{R}_{+}. \]

The function takes an input $$x$$ and returns a positive float value.

float_copy_sign

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

The function takes two arguments $$x, y \in \mathbb{R}$$ and returns $$x$$ such that it has the same sign as $$y$$.

float_flip_sign

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

The function flips the sign of a given input value $$x \in \mathbb{R}$$.

float_sign

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

The function takes an input $$x \in \mathbb{R}$$ and returns the sign of the input, indicating whether it is positive (+1.0), negative (-1.0), or zero (0.0).

floor

</> 
pub fn floor(
  x: Float,
  digits: Option(Int),
) -> Result(Float, String)

The floor function rounds input $$x \in \mathbb{R}$$ to the nearest integer value (at the specified digit) that is less than or equal to the input $$x$$.

Note: The floor function is used as an alias for the rounding function round with rounding mode RoundDown.

Details

For example, $$12.0654$$ is rounded to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.0$$ for 1 digits after the decimal point (digits = 1)
  • $$12.06$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)
Example 
import gleeunit/should
import gleam/option
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.floor(12.0654, option.Some(1))
  |> should.equal(Ok(12.0))

  piecewise.floor(12.0654, option.Some(2))
  |> should.equal(Ok(12.06))

  piecewise.floor(12.0654, option.Some(3))
  |> should.equal(Ok(12.065))
}

int_absolute_difference

</> 
pub fn int_absolute_difference(a: Int, b: Int) -> Int

The absolute difference:

\[ \forall x, y \in \mathbb{Z}, \; |x - y| \in \mathbb{Z}_{+}. \]

The function takes two inputs $$x$$ and $$y$$ and returns a positive integer value which is the the absolute difference of the inputs.

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

pub fn example() {
  piecewise.absolute_difference(-10, 10)
  |> should.equal(20)

  piecewise.absolute_difference(0, -2)
  |> should.equal(2)
}

int_absolute_value

</> 
pub fn int_absolute_value(x: Int) -> Int

The absolute value:

\[ \forall x, y \in \mathbb{Z}, \; |x| \in \mathbb{Z}_{+}. \]

The function takes an input $$x$$ and returns a positive integer value.

int_copy_sign

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

The function takes two arguments $$x, y \in \mathbb{Z}$$ and returns $$x$$ such that it has the same sign as $$y$$.

int_flip_sign

</> 
pub fn int_flip_sign(x: Int) -> Int

The function flips the sign of a given input value $$x \in \mathbb{Z}$$.

int_sign

</> 
pub fn int_sign(x: Int) -> Int

The function takes an input $$x \in \mathbb{Z}$$ and returns the sign of the input, indicating whether it is positive (+1), negative (-1), or zero (0).

list_maximum

</> 
pub fn list_maximum(
  arr: List(a),
  compare: fn(a, a) -> Order,
) -> Result(a, String)

Returns the maximum value of a given list.

Example: 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example () {
  // An empty lists returns an error
  []
  |> piecewise.list_maximum(float.compare)
  |> should.be_error()

  // Valid input returns a result
  [4.0, 4.0, 3.0, 2.0, 1.0]
  |> piecewise.list_maximum(float.compare)
  |> should.equal(Ok(4.0))
}

list_minimum

</> 
pub fn list_minimum(
  arr: List(a),
  compare: fn(a, a) -> Order,
) -> Result(a, String)

Returns the minimum value of a given list.

Example: 
import gleeunit/should
import gleam/int
import gleam_community/maths/piecewise

pub fn example () {
  // An empty lists returns an error
  []
  |> piecewise.list_minimum(int.compare)
  |> should.be_error()

  // Valid input returns a result
  [4, 4, 3, 2, 1]
  |> piecewise.list_minimum(int.compare)
  |> should.equal(Ok(1))
}

maximum

</> 
pub fn maximum(x: a, y: a, compare: fn(a, a) -> Order) -> a

The maximum function takes two arguments $$x, y$$ along with a function for comparing $$x, y$$. The function returns the largest of the two given values.

Example 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.maximum(2.0, 1.5, float.compare)
  |> should.equal(1.5)

  piecewise.maximum(1.5, 2.0, float.compare)
  |> should.equal(1.5)
}

minimum

</> 
pub fn minimum(x: a, y: a, compare: fn(a, a) -> Order) -> a

The minimum function takes two arguments $$x, y$$ along with a function for comparing $$x, y$$. The function returns the smallest of the two given values.

Example 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.minimum(2.0, 1.5, float.compare)
  |> should.equal(1.5)

  piecewise.minimum(1.5, 2.0, float.compare)
  |> should.equal(1.5)
}

minmax

</> 
pub fn minmax(x: a, y: a, compare: fn(a, a) -> Order) -> #(a, a)

The minmax function takes two arguments $$x, y$$ along with a function for comparing $$x, y$$. The function returns a tuple with the smallest value first and largest second.

Example 
import gleeunit/should
import gleam/float
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.minmax(2.0, 1.5, float.compare)
  |> should.equal(#(1.5, 2.0))

  piecewise.minmax(1.5, 2.0, float.compare)
  |> should.equal(#(1.5, 2.0))
}

round

</> 
pub fn round(
  x: Float,
  digits: Option(Int),
  mode: Option(RoundingMode),
) -> Result(Float, String)

The function rounds a float to a specific number of digits (after the decimal place or before if negative) using a specified rounding mode.

Valid rounding modes include:

  • RoundNearest (default): The input $$x$$ is rounded to the nearest integer value (at the specified digit) with ties (fractional values of 0.5) being rounded to the nearest even integer.
  • RoundTiesAway: The input $$x$$ is rounded to the nearest integer value (at the specified digit) with ties (fractional values of 0.5) being rounded away from zero (C/C++ rounding behavior).
  • RoundTiesUp: The input $$x$$ is rounded to the nearest integer value (at the specified digit) with ties (fractional values of 0.5) being rounded towards $$+\infty$$ (Java/JavaScript rounding behaviour).
  • RoundToZero: The input $$x$$ is rounded to the nearest integer value (at the specified digit) that is less than or equal to the absolute value of the input $$x$$. An alias for this rounding mode is truncate.
  • RoundDown: The input $$x$$ is rounded to the nearest integer value (at the specified digit) that is less than or equal to the input $$x$$. An alias for this rounding mode is floor.
  • RoundUp: The input $$x$$ is rounded to the nearest integer value (at the specified digit) that is larger than or equal to the input $$x$$. An alias for this rounding mode is ceiling.
Details

The RoundNearest rounding mode, rounds $$12.0654$$ to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.1$$ for 1 digit after the decimal point (digits = 1)
  • $$12.07$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)

The RoundTiesAway rounding mode, rounds $$12.0654$$ to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.1$$ for 1 digit after the decimal point (digits = 1)
  • $$12.07$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)

The RoundTiesUp rounding mode, rounds $$12.0654$$ to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.1$$ for 1 digits after the decimal point (digits = 1)
  • $$12.07$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)

The RoundToZero rounding mode, rounds $$12.0654$$ to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.0$$ for 1 digit after the decimal point (digits = 1)
  • $$12.06$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)

The RoundDown rounding mode, rounds $$12.0654$$ to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.0$$ for 1 digits after the decimal point (digits = 1)
  • $$12.06$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)

The RoundUp rounding mode, rounds $$12.0654$$ to:

  • $$13.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.1$$ for 1 digit after the decimal point (digits = 1)
  • $$12.07$$ for 2 digits after the decimal point (digits = 2)
  • $$12.066$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$20.0$$ for 1 digit places before the decimal point (digit = -1)
  • $$100.0$$ for 2 digits before the decimal point (digits = -2)
  • $$1000.0$$ for 3 digits before the decimal point (digits = -3)
Example 
import gleeunit/should
import gleam/option
import gleam_community/maths/piecewise

pub fn example() {
  // The default number of digits is 0 if None is provided
  piecewise.round(12.0654, option.None, option.Some(piecewise.RoundNearest))
  |> should.equal(Ok(12.0))

  // The default rounding mode is "RoundNearest" if None is provided 
  piecewise.round(12.0654, option.None, option.None)
  |> should.equal(Ok(12.0))

  // Try different rounding modes
  piecewise.round(12.0654, option.Some(2), option.Some(piecewise.RoundNearest))
  |> should.equal(Ok(12.07))

  piecewise.round(12.0654, option.Some(2), option.Some(piecewise.RoundTiesAway))
  |> should.equal(Ok(12.07))

  piecewise.round(12.0654, option.Some(2), option.Some(piecewise.RoundTiesUp))
  |> should.equal(Ok(12.07))

  piecewise.round(12.0654, option.Some(2), option.Some(piecewise.RoundToZero))
  |> should.equal(Ok(12.06))

  piecewise.round(12.0654, option.Some(2), option.Some(piecewise.RoundDown))
  |> should.equal(Ok(12.06))

  piecewise.round(12.0654, option.Some(2), option.Some(piecewise.RoundUp))
  |> should.equal(Ok(12.07))
}

truncate

</> 
pub fn truncate(
  x: Float,
  digits: Option(Int),
) -> Result(Float, String)

The truncate function rounds a given input $$x \in \mathbb{R}$$ to the nearest integer value (at the specified digit) that is less than or equal to the absolute value of the input $$x$$.

Note: The truncate function is used as an alias for the rounding function round with rounding mode RoundToZero.

Details

For example, $$12.0654$$ is rounded to:

  • $$12.0$$ for 0 digits after the decimal point (digits = 0)
  • $$12.0$$ for 1 digits after the decimal point (digits = 1)
  • $$12.06$$ for 2 digits after the decimal point (digits = 2)
  • $$12.065$$ for 3 digits after the decimal point (digits = 3)

It is also possible to specify a negative number of digits. In that case, the negative number refers to the digits before the decimal point.

  • $$10.0$$ for 1 digit before the decimal point (digits = -1)
  • $$0.0$$ for 2 digits before the decimal point (digits = -2)
  • $$0.0$$ for 3 digits before the decimal point (digits = -3)
Example 
import gleeunit/should
import gleam/option
import gleam_community/maths/piecewise

pub fn example() {
  piecewise.truncate(12.0654, option.Some(1))
  |> should.equal(Ok(12.0))

  piecewise.truncate(12.0654, option.Some(2))
  |> should.equal(Ok(12.0))

  piecewise.truncate(12.0654, option.Some(3))
  |> should.equal(Ok(12.0))
}
✨ Search Document