ranged_int/interface

The ranged integer “interface”.

This module contains types and functions to be implemented and used to create custom ranged integer types.

See the README for instructions on how to create your own type with this module.

Types

Interface

The ranged integer interface that needs to be passed to math operations.

To allow for overflowing, the second type parameter must be Overflowable.

pub type Interface(a, overflow_mode) {
  Interface(
    to_bigint: fn(a) -> BigInt,
    from_bigint_unsafe: fn(BigInt) -> a,
    limits: fn() -> Limits(overflow_mode),
  )
}

Constructors

```
Interface(
  to_bigint: fn(a) -> BigInt,
  from_bigint_unsafe: fn(BigInt) -> a,
  limits: fn() -> Limits(overflow_mode),
)
```
Arguments
- to_bigint
  
  A function to convert the ranged integer into a big integer.
- from_bigint_unsafe
  
  A function to convert a big integer to the ranged integer. No limit checking is done, hence the name “unsafe”. This is used internally when the limits have already been checked.
- limits
  
  A function to return the limits of the ranged integer.

Limits

</>

The minimum and maximum limits of a ranged integer.

pub opaque type Limits(overflow_mode)

OpResult

</>

Result of math operations: a new ranged integer or an overflow.

An overflow result may occur even for non-overflowable integers. The difference is that the overflow function cannot be called to calculate the overflowed result for a non-overflowable integer.

pub type OpResult(a) =
  Result(a, utils.Overflow)

Functions

compare

</>

pub fn compare(
  int1: a,
  int2: a,
  interface: Interface(a, b),
) -> Order

Compare two ranged integers, returning an order that denotes if int1 is lower, bigger than, or equal to int2.

eject

</>

pub fn eject(
  value: Result(a, Overflow),
  interface: Interface(a, b),
) -> BigInt

Eject the result of an operation to big integer. The big integer may be outside the range of the original ranged integers.

fallible_op

</>

pub fn fallible_op(
  int1: a,
  int2: BigInt,
  interface: Interface(a, b),
  op: fn(BigInt, BigInt) -> Result(BigInt, c),
) -> Result(Result(a, Overflow), c)

Run a math operation that may fail on a ranged integer and an unranged big integer.

Some functions such as bigi.divide_no_zero will return an error if the arguments are invalid. This error is passed upwards by this function.

from_bigint

</>

pub fn from_bigint(
  value: BigInt,
  interface: Interface(a, b),
) -> Result(a, Overflow)

Create a ranged integer from a big integer.

math_op

</>

pub fn math_op(
  int1: a,
  int2: BigInt,
  interface: Interface(a, b),
  op: fn(BigInt, BigInt) -> BigInt,
) -> Result(a, Overflow)

Run a math operation on a ranged integer and an unranged big integer.

math_op_unary

</>

pub fn math_op_unary(
  int: a,
  interface: Interface(a, b),
  op: fn(BigInt) -> BigInt,
) -> Result(a, Overflow)

Run a unary math operation on a ranged integer.

max_limit

</>

pub fn max_limit(max: BigInt) -> Limits(NonOverflowable)

Construct limits for a non-overflowable ranged integer that only has a maximum limit. The given limit is inclusive.

min_limit

</>

pub fn min_limit(min: BigInt) -> Limits(NonOverflowable)

Construct limits for a non-overflowable ranged integer that only has a minimum limit. The given limit is inclusive.

overflow

</>

pub fn overflow(
  value: Result(a, Overflow),
  interface: Interface(a, Overflowable),
) -> a

Map the overflow result of an operation to the integer’s allowed range.

The overflow is calculated using a modulo against the amount of integers in the allowed range. This matches the unsigned integer overflow logic of C/C++ but is also defined for signed (negative) values.

This can only be called for overflowable integers.

overflowable_limits

</>

pub fn overflowable_limits(
  min: BigInt,
  max: BigInt,
) -> Limits(Overflowable)

Construct limits for an overflowable ranged integer. The given limits are inclusive.

Constructors

Arguments

Constructors

Constructors