# 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))
}