Number Library

Stof's standard number library ("Number").

See Primitive Types, Units, and Casting/Conversions for more information on number types in Stof.

Common Value Functions

Number.toString(val: int | float | units): str

#[test]
fn test() {
    let a = 100.toString();
    let b = Number.toString(100);
    assertEq(a, b);
    assertEq(a, "100");
}

Number.or(val: int | float | units, ...): unknown

Returns the first non-empty (null or void) argument, just like the Standard Library "or" function.

#[test]
fn test() {
    let val = 5;
    assertEq(val.or(2), 5);
    
    val = null;
    assertEq(val.or(3), 3);
}

Number Functions

Number.round(val: int | float | units, places?: int): float

Round this val to the nearest integer. If value is half-way between two integers, rounds away from 0.0. If given a number of places to round to, move the decimal right that many places, round, then moves it back.

#[test]
fn round() {
    assertEq(12.23456.round(), 12);
    assertEq(12.23456.round(2), 12.23);
    assertEq(12.23456.round(4), 12.2346);
}

Number.pow(val: int | float | units, power: int | float): float

Raises a number to a power.

#[test]
fn pow() {
    assertEq(2.pow(3), 8);
    assertEq(Number.pow(2, 3), 8);
}

Number.sqrt(val: int | float | units): float

Return the square root of a number.

#[test]
fn sqrt() {
    assertEq(4.sqrt(), 2);
}

Number.cbrt(val: int | float | units): float

Return the cube root of a number.

#[test]
fn cbrt() {
    assertEq(8.cbrt(), 2);
}

Number.abs(val: int | float | units): float

Return the absolute value of a number.

#[test]
fn abs() {
    assertEq(-3.abs(), 3);
    assertEq(3.abs(), 3);
    assertEq(Number.abs(box(-3434)), 3434);
}

Number.floor(val: int | float | units): float

Return the largest integer less than or equal to "val".

#[test]
fn floor() {
    assertEq(1.45.floor(), 1);
}

Number.ceil(val: int | float | units): float

Return the smallest integer greater than or equal to "val".

#[test]
fn ceil() {
    assertEq(1.45.ceil(), 2);
}

Number.trunc(val: int | float | units): float

Return the integer part of "val". Non-integer values are always truncated towards zero.

#[test]
fn test() {
    assertEq(12.7.trunc(), 12);
}

Number.fract(val: int | float | units): float

Return the fractional part of "val".

#[test]
fn fract() {
    assertEq(12.5.fract(), 0.5);
}

Number.signum(val: int | float | units): float

Returns a number representing the sign of "val".

• 1, the number is positive

• -1, the number is negative

Number.exp(val: int | float | units): float

Returns the exponential function e^(val) .

Number.exp2(val: int | float | units): float

Returns 2^(val).

Number.ln(val: int | float | units): float

Returns the natural log of val: ln(val).

Number.log(val: int | float | units, base: int | float): float

Returns the logarithm of the number with respect to an arbitrary base.

Number.sin(val: int | float | units): float

Computes the sine of a number (in radians).

#[test]
fn angles_trig() {
    assertEq(90deg.sin(), 1);
    assertEq(270deg.sin(), -1);
}

Number.cos(val: int | float | units): float

Computes the cosine of a number (in radians).

#[test]
fn angles_trig() {
    assertEq(0deg.cos(), 1);
    assertEq(180deg.cos(), -1);
}

Number.tan(val: int | float | units): float

Computes the tangent of a number (in radians).

#[test]
fn angles_trig() {
    assertEq(0deg.tan(), 0);
}

Number.asin(val: int | float | units): rad

Computes the arcsine of a number. Return value is in radians in the range -pi/2, pi/2 or null if the number is outside the range -1, 1.

#[test]
fn test() {
    assertEq(-1.asin(), 270deg);
}

Number.acos(val: int | float | units): rad

Computes the arccosine of a number. Return value is in radians in the range 0, pi or null if the number is outside the range -1, 1.

#[test]
fn test() {
    assertEq(-1.acos(), 180deg);
}

Number.atan(val: int | float | units): rad

Computes the arctangent of a number. Return value is in radians in the range -pi/2, pi/2.

#[test]
fn test() {
    assertEq(0.atan(), 0deg);
}

Number.atan2(val: int | float | units, other: float): rad

Computes the four quadrant arctangent of "val" and "other" in radians.

• x = 0, y = 0: 0

• x >= 0: arctan(y/x) -> [-pi/2, pi/2]

• y >= 0: arctan(y/x) + pi -> (pi/2, pi]

• y < 0: arctan(y/x) - pi -> (-pi, -pi/2)

Number.sinh(val: int | float | units): float

Hyperbolic sine function.

Number.cosh(val: int | float | units): float

Hyperbolic cosine function.

Number.tanh(val: int | float | units): float

Hyperbolic tangent function.

Number.asinh(val: int | float | units): float

Inverse hyperbolic sine function.

Number.acosh(val: int | float | units): float

Inverse hyperbolic cosine function.

Number.atanh(val: int | float | units): float

Inverse hyperbolic tangent function.

Iteration

Number.len(val: int | float | units): int

Returns the integer part of "val". Non-integer values are truncated towards zero.

This function is provided to support iteration of numbers.

Number.at(val: int | float | units, index: int): int

Returns the integer part of "index" if index is less than the integer part of "val", otherwise, returns the integer part of "val". Non-integer values for both "val" and "index" are truncated towards zero.

#[test]
fn test() {
    // For loops use "len" to get the length and "at" to get each value
    for (i in 10) {
        pln(i); // will print 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    }
}

Units

Number.units(val: units): str | null

Returns the units of this number or null if no units are defined.

#[test]
fn test() {
    assertEq(19km.units(), "km");
    assertNull(19.units());
}

Number.removeUnits(val: units): float

Remove the units of this number if any units are defined. Otherwise, returns a clone of "val".

#[test]
fn test() {
    let val = 20s;
    assertEq(val.units(), "s"); // seconds
    
    val = val.removeUnits();
    assertNull(val.units());
}

Number.hasUnits(val: int | float | units): bool

Return true if this number has units defined for it.

#[test]
fn test() {
    assert(10F.hasUnits());
    assertNot(10.hasUnits());
}

Number.isAngle(val: int | float | units): bool

Return true if this number has angle units defined for it.

#[test]
fn test() {
    assert(10deg.isAngle());
    assertNot(10F.isAngle());
}

Number.isDegrees(val: int | float | units): bool

Return true if this number has angle units of Degrees.

#[test]
fn test() {
    assert(10deg.isDegrees());
    assertNot(10rad.isDegrees());
}

Number.isRadians(val: int | float | units): bool

Return true if this number has angle units of Radians.

#[test]
fn test() {
    assert(10rad.isRadians());
    assertNot(10deg.isRadians());
}

Number.isPositiveDegrees(val: int | float | units): bool

Return true if this number has angle units of Positive Degrees. See Units for more information on positive degrees.

#[test]
fn test() {
    assert(10pdeg.isPositiveDegrees());
    assertNot(10deg.isPositiveDegrees());
}

Number.isPositiveRadians(val: int | float | units): bool

Return true if this number has angle units of Positive Radians. See Units for more information on positive radians.

#[test]
fn test() {
    assert(10prad.isPositiveRadians());
    assertNot(10rad.isPositiveRadians());
}

Number.isTemperature(val: int | float | units): bool

Return true if this number has units of temperature defined for it.

#[test]
fn test() {
    assert(10C.isTemperature());
    assertNot(10km.isTemperature());
}

Number.isLength(val: int | float | units): bool

Return true if this number has units of length defined for it.

#[test]
fn test() {
    assert(10m.isLength());
    assertNot(10ms.isLength());
}

Number.isTime(val: int | float | units): bool

Return true if this number has units of time defined for it.

#[test]
fn test() {
    assert(10ns.isTime());
    assertNot(10m.isTime());
}

Number.isMass(val: int | float | units): bool

Return true if this number has units of mass defined for it.

#[test]
fn test() {
    assert(10g.isMass());
    assertNot(10m.isMass());
}