gleam_community_maths - v1.0.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