Builtins

USE_COLOR

USE_COLOR : Bool

Whether or not the console prefers ANSI color escape sequences in the output.

ask

ask : func(prompt: Text, bold: Bool = yes, force_tty: Bool = yes -> Text?)

Gets a line of user input text with a prompt.

When a program is receiving input from a pipe or writing its output to a pipe, this flag (which is enabled by default) forces the program to write the prompt to /dev/tty and read the input from /dev/tty, which circumvents the pipe. This means that foo | ./tomo your-program | baz will still show a visible prompt and read user input, despite the pipes. Setting this flag to no will mean that the prompt is written to stdout and input is read from stdin, even if those are pipes.

Return: A line of user input text without a trailing newline, or empty text if something went wrong (e.g. the user hit Ctrl-D).

Example:

assert ask("What's your name? ") == "Arthur Dent"

at_cleanup

at_cleanup : func(fn: func() -> Void)

Register a function that runs at cleanup time for Tomo programs. Cleanup time happens when a program exits (see atexit() in C), or immediately before printing error messages in a call to fail(). This allows for terminal cleanup so error messages can be visible as the program shuts down.

Use this API very carefully, because errors that occur during cleanup functions may make it extremely hard to figure out what's going on. Cleanup functions should be designed to not error under any circumstances.

Return: Nothing.

Example:

at_cleanup(func()
    _ := (/tmp/file.txt).remove(ignore_missing=yes)
)

breakpoint

breakpoint : func(-> Void)

Stops the program in a debugger at the point where it is called. Running the program under tomo run --debug gives a debugger prompt here, showing the surrounding source and the values of the variables in scope.

Only a program compiled with --debug contains this call at all. Without that flag it compiles to nothing, so a breakpoint() left in the source costs a release build nothing and does nothing if the program is run outside a debugger. See docs/debugging.md.

Return: Nothing.

Example:

total := 0
for i in 10
    total += i
breakpoint() # `tomo run --debug` stops here, with `total` and `i` in scope

exit

exit : func(message: Text? = none, status: Int32 = Int32(1) -> Abort)

Exits the program with a given status and optionally prints a message.

Return: This function never returns.

Example:

exit("Goodbye forever!", Int32(1))

fail

fail : func(message: Text -> Abort)

Prints a message to the console, aborts the program, and prints a stack trace.

Return: Nothing, aborts the program.

Example:

fail("Oh no!")

getenv

getenv : func(name: Text -> Text?)

Gets an environment variable.

Return: If set, the environment variable's value, otherwise, none.

Example:

assert getenv("TERM") == "xterm-256color"
assert getenv("not_a_variable") == none

print

print : func(text: Text, newline: Bool = yes -> Void)

Prints a message to the console (alias for say()).

Return: Nothing.

Example:

print("Hello ", newline=no)
print("world!")

say

say : func(text: Text, newline: Bool = yes -> Void)

Prints a message to the console.

Return: Nothing.

Example:

say("Hello ", newline=no)
say("world!")

setenv

setenv : func(name: Text, value: Text? -> Void)

Sets an environment variable.

Return: Nothing.

Example:

setenv("FOOBAR", "xyz")

sleep

sleep : func(seconds: Num -> Void)

Pause execution for a given number of seconds.

Return: Nothing.

Example:

sleep(1.5)

Bool

Bool.parse

Bool.parse : func(text: Text, remainder: &Text? = none -> Bool?)

Converts a text representation of a boolean value into a boolean. The accepted values are yes/no, true/false, on/off, and 1/0, each written in lowercase (true), uppercase (TRUE), or capitalized (True). Mixed casings like tRuE are not accepted.

Return: yes if the string matches a recognized truthy boolean value; otherwise return no.

Example:

assert Bool.parse("yes") == yes
assert Bool.parse("no") == no
assert Bool.parse("???") == none

assert Bool.parse("yesJUNK") == none
remainder : Text
assert Bool.parse("yesJUNK", &remainder) == yes
assert remainder == "JUNK"

Byte

Byte.get_bit

Byte.get_bit : func(i: Byte, bit_index: Int -> Bool)

In the binary representation of a byte, check whether a given bit index is set to 1 or not.

The bit index must be between 1-8 or a runtime error will be produced.

Return: Whether or not the given bit index is set to 1 in the byte.

Example:

assert not Byte(6).get_bit(1)
assert Byte(6).get_bit(2)
assert Byte(6).get_bit(3)
assert not Byte(6).get_bit(4)

Byte.hex

Byte.hex : func(byte: Byte, uppercase: Bool = yes, prefix: Bool = no -> Text)

Convert a byte to a hexidecimal text representation.

Return: The byte as a hexidecimal text.

Example:

assert Byte(18).hex(prefix=yes) == "0x12"

Byte.is_between

Byte.is_between : func(x: Byte, low: Byte, high: Byte -> Bool)

Determines if an integer is between two numbers (inclusive).

Return: yes if a <= x and x <= b or b <= x and x <= a, otherwise no

Example:

assert Byte(7).is_between(1, 10)
assert Byte(7).is_between(10, 1)
assert not Byte(7).is_between(100, 200)
assert Byte(7).is_between(1, 7)

Byte.parse

Byte.parse : func(text: Text, base: Int? = none, remainder: &Text? = none -> Byte?)

Parse a byte literal from text.

Return: The byte parsed from the text, if successful, otherwise none.

Example:

assert Byte.parse("5") == Byte(5)
assert Byte.parse("asdf") == none
assert Byte.parse("123xyz") == none

remainder : Text
assert Byte.parse("123xyz", remainder=&remainder) == Byte(123)
assert remainder == "xyz"

Byte.to

Byte.to : func(first: Byte, last: Byte, step: Int8? = none -> func(->Byte?))

Returns an iterator function that iterates over the range of bytes specified.

Return: An iterator function that returns each byte in the given range (inclusive).

Example:

iter := Byte(2).to(4)
assert iter() == Byte(2)
assert iter() == Byte(3)
assert iter() == Byte(4)
assert iter() == none

assert [x for x in Byte(2).to(5)] == [Byte(2), Byte(3), Byte(4), Byte(5)]
assert [x for x in Byte(5).to(2)] == [Byte(5), Byte(4), Byte(3), Byte(2)]
assert [x for x in Byte(2).to(5, step=2)] == [Byte(2), Byte(4)]

CString

CString.as_text

CString.as_text : func(str: CString -> Text?)

Convert a C string to Text. This is the same conversion that Text(str) performs.

A C string is an arbitrary sequence of non-NUL bytes, but Text holds Unicode, so this returns none when the bytes are not valid UTF-8.

Return: The C string as a Text, or none if it is not valid UTF-8.

Example:

assert CString("Hello").as_text() == "Hello"
assert Text(CString("Hello"))! == "Hello"

CString.bytes

CString.bytes : func(str: CString -> [Byte])

Convert a C string to a list of its raw bytes.

Return: A list of bytes ([Byte]) representing the C string's contents.

Example:

assert CString("Hi").bytes() == [72, 105]

CString.join

CString.join : func(glue: CString, pieces: [CString] -> CString)

Join a list of C strings together with a separator.

Return: A C string of the joined together bits.

Example:

assert CString(",").join([CString("a"), CString("b")]) == CString("a,b")

Float64

Float64.1_PI

Float64.1_PI : Float64

The constant $\frac{1}{\pi}$.

Float64.2_PI

Float64.2_PI : Float64

The constant $2 \times \pi$.

Float64.2_SQRTPI

Float64.2_SQRTPI : Float64

The constant $2 \times \sqrt{\pi}$.

Float64.E

Float64.E : Float64

The base of the natural logarithm ($e$).

Float64.INF

Float64.INF : Float64

Positive infinity.

Float64.LN10

Float64.LN10 : Float64

The natural logarithm of 10.

Float64.LN2

Float64.LN2 : Float64

The natural logarithm of 2.

Float64.LOG2E

Float64.LOG2E : Float64

The base 2 logarithm of $e$

Float64.PI

Float64.PI : Float64

Pi ($\pi$).

Float64.PI_2

Float64.PI_2 : Float64

$\frac{\pi}{2}$

Float64.PI_4

Float64.PI_4 : Float64

$\frac{\pi}{4}$

Float64.SQRT1_2

Float64.SQRT1_2 : Float64

$\sqrt{\frac{1}{2}}$

Float64.SQRT2

Float64.SQRT2 : Float64

$\sqrt{2}$

Float64.TAU

Float64.TAU : Float64

Tau ($2 \times \pi$)

Float64.abs

Float64.abs : func(n: Float64 -> Float64)

Calculates the absolute value of a number.

Return: The absolute value of n.

Example:

assert Float64(-3.5).abs() == 3.5

Float64.acos

Float64.acos : func(x: Float64 -> Float64)

Computes the arc cosine of a number.

Return: The arc cosine of x in radians.

Example:

assert Float64(0.0).acos().near(1.5707963267948966)

Float64.acosh

Float64.acosh : func(x: Float64 -> Float64)

Computes the inverse hyperbolic cosine of a number.

Return: The inverse hyperbolic cosine of x.

Example:

assert Float64(1.0).acosh() == 0

Float64.asin

Float64.asin : func(x: Float64 -> Float64)

Computes the arc sine of a number.

Return: The arc sine of x in radians.

Example:

assert Float64(0.5).asin().near(0.5235987755982989)

Float64.asinh

Float64.asinh : func(x: Float64 -> Float64)

Computes the inverse hyperbolic sine of a number.

Return: The inverse hyperbolic sine of x.

Example:

assert Float64(0.0).asinh() == 0

Float64.atan

Float64.atan : func(x: Float64 -> Float64)

Computes the arc tangent of a number.

Return: The arc tangent of x in radians.

Example:

assert Float64(1.0).atan().near(0.7853981633974483)

Float64.atan2

Float64.atan2 : func(x: Float64, y: Float64 -> Float64)

Computes the arc tangent of the quotient of two numbers.

Return: The arc tangent of x/y in radians.

Example:

assert Float64.atan2(1, 1).near(0.7853981633974483)

Float64.atanh

Float64.atanh : func(x: Float64 -> Float64)

Computes the inverse hyperbolic tangent of a number.

Return: The inverse hyperbolic tangent of x.

Example:

assert Float64(0.5).atanh().near(0.5493061443340549)

Float64.cbrt

Float64.cbrt : func(x: Float64 -> Float64)

Computes the cube root of a number.

Return: The cube root of x.

Example:

assert Float64(27.0).cbrt() == 3

Float64.ceil

Float64.ceil : func(x: Float64 -> Float64)

Rounds a number up to the nearest integer.

Return: The smallest integer greater than or equal to x.

Example:

assert Float64(3.2).ceil() == 4

Float64.clamped

Float64.clamped : func(x: Float64, low: Float64, high: Float64 -> Float64)

Returns the given number clamped between two values so that it is within that range.

Return: The first argument clamped between the other two arguments.

Example:

assert Float64(2.5).clamped(5.5, 10.5) == 5.5

Float64.copysign

Float64.copysign : func(x: Float64, y: Float64 -> Float64)

Copies the sign of one number to another.

Return: A number with the magnitude of x and the sign of y.

Example:

assert Float64(3.0).copysign(-1) == -3

Float64.cos

Float64.cos : func(x: Float64 -> Float64)

Computes the cosine of a number (angle in radians).

Return: The cosine of x.

Example:

assert Float64(0.0).cos() == 1

Float64.cosh

Float64.cosh : func(x: Float64 -> Float64)

Computes the hyperbolic cosine of a number.

Return: The hyperbolic cosine of x.

Example:

assert Float64(0.0).cosh() == 1

Float64.erf

Float64.erf : func(x: Float64 -> Float64)

Computes the error function of a number.

Return: The error function of x.

Example:

assert Float64(0.0).erf() == 0

Float64.erfc

Float64.erfc : func(x: Float64 -> Float64)

Computes the complementary error function of a number.

Return: The complementary error function of x.

Example:

assert Float64(0.0).erfc() == 1

Float64.exp

Float64.exp : func(x: Float64 -> Float64)

Computes the exponential function $e^x$ for a number.

Return: The value of $e^x$.

Example:

assert Float64(1.0).exp().near(2.718281828459045)

Float64.exp2

Float64.exp2 : func(x: Float64 -> Float64)

Computes $2^x$ for a number.

Return: The value of $2^x$.

Example:

assert Float64(3.0).exp2() == 8

Float64.expm1

Float64.expm1 : func(x: Float64 -> Float64)

Computes $e^x - 1$ for a number.

Return: The value of $e^x - 1$.

Example:

assert Float64(1.0).expm1().near(1.7182818284590453)

Float64.fdim

Float64.fdim : func(x: Float64, y: Float64 -> Float64)

Computes the positive difference between two numbers.

Return: The positive difference $\max(0, x - y)$.

Example:

assert Float64(5.0).fdim(3) == 2

Float64.floor

Float64.floor : func(x: Float64 -> Float64)

Rounds a number down to the nearest integer.

Return: The largest integer less than or equal to x.

Example:

assert Float64(3.7).floor() == 3

Float64.hypot

Float64.hypot : func(x: Float64, y: Float64 -> Float64)

Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers.

Return: The Euclidean norm of x and y.

Example:

assert Float64.hypot(3, 4) == 5

Float64.is_between

Float64.is_between : func(x: Float64, low: Float64, high: Float64 -> Bool)

Determines if a number is between two numbers (inclusive).

Return: yes if a <= x and x <= b or b <= x and x <= a, otherwise no

Example:

assert Float64(7.5).is_between(1, 10)
assert Float64(7.5).is_between(10, 1)
assert not Float64(7.5).is_between(100, 200)
assert Float64(7.5).is_between(1, 7.5)

Float64.isfinite

Float64.isfinite : func(n: Float64 -> Bool)

Checks if a number is finite.

Return: yes if n is finite, no otherwise.

Example:

assert Float64(1.0).isfinite()
assert not Float64.INF.isfinite()

Float64.isinf

Float64.isinf : func(n: Float64 -> Bool)

Checks if a number is infinite.

Return: yes if n is infinite, no otherwise.

Example:

assert Float64.INF.isinf()
assert not Float64(1.0).isinf()

Float64.j0

Float64.j0 : func(x: Float64 -> Float64)

Computes the Bessel function of the first kind of order 0.

Return: The Bessel function of the first kind of order 0 of x.

Example:

assert Float64(0.0).j0() == 1

Float64.j1

Float64.j1 : func(x: Float64 -> Float64)

Computes the Bessel function of the first kind of order 1.

Return: The Bessel function of the first kind of order 1 of x.

Example:

assert Float64(0.0).j1() == 0

Float64.log

Float64.log : func(x: Float64 -> Float64)

Computes the natural logarithm (base $e$) of a number.

Return: The natural logarithm of x.

Example:

assert Float64.E.log() == 1

Float64.log10

Float64.log10 : func(x: Float64 -> Float64)

Computes the base-10 logarithm of a number.

Return: The base-10 logarithm of x.

Example:

assert Float64(100.0).log10() == 2

Float64.log1p

Float64.log1p : func(x: Float64 -> Float64)

Computes $\log(1 + x)$ for a number.

Return: The value of $\log(1 + x)$.

Example:

assert Float64(1.0).log1p().near(0.6931471805599453)

Float64.log2

Float64.log2 : func(x: Float64 -> Float64)

Computes the base-2 logarithm of a number.

Return: The base-2 logarithm of x.

Example:

assert Float64(8.0).log2() == 3

Float64.logb

Float64.logb : func(x: Float64 -> Float64)

Computes the binary exponent (base-2 logarithm) of a number.

Return: The binary exponent of x.

Example:

assert Float64(8.0).logb() == 3

Float64.mix

Float64.mix : func(amount: Float64, x: Float64, y: Float64 -> Float64)

Interpolates between two numbers based on a given amount.

Return: The interpolated number between x and y based on amount.

Example:

assert Float64(0.5).mix(10, 20) == 15
assert Float64(0.25).mix(10, 20) == 12.5

Float64.near

Float64.near : func(x: Float64, y: Float64, ratio: Float64 = 1e-9, min_epsilon: Float64 = 1e-9 -> Bool)

Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is small enough, they are considered near each other.

Return: yes if x and y are approximately equal within the specified tolerances, no otherwise.

Example:

assert Float64(1.0).near(1.000000001)
assert Float64(100.0).near(110, ratio=0.1)
assert Float64(5.0).near(5.1, min_epsilon=0.1)

Float64.nextafter

Float64.nextafter : func(x: Float64, y: Float64 -> Float64)

Computes the next representable value after a given number towards a specified direction.

Return: The next representable value after x in the direction of y.

Example:

assert Float64(1.0).nextafter(1.1) == 1.0000000000000002

Float64.parse

Float64.parse : func(text: Text, remainder: &Text? = none -> Float64?)

Converts a text representation of a number into a floating-point number.

Return: The number represented by the text or none if the entire text can't be parsed as a number.

Example:

assert Float64.parse("3.14") == 3.14
assert Float64.parse("1e3") == 1000
assert Float64.parse("1.5junk") == none
remainder : Text
assert Float64.parse("1.5junk", &remainder) == 1.5
assert remainder == "junk"

Float64.percent

Float64.percent : func(n: Float64, precision: Float64 = 0.01 -> Text)

Convert a number into a percentage text with a percent sign.

Return: A text representation of the number as a percentage with a percent sign.

Example:

assert Float64(0.5).percent() == "50%"
assert (Float64(1.) / Float64(3.)).percent(2) == "34%"
assert (Float64(1.) / Float64(3.)).percent(precision=0.0001) == "33.3333%"
assert (Float64(1.) / Float64(3.)).percent(precision=10.) == "30%"

Float64.rint

Float64.rint : func(x: Float64 -> Float64)

Rounds a number to the nearest integer, with ties rounded to the nearest even integer.

Return: The nearest integer value of x.

Example:

assert Float64(3.5).rint() == 4
assert Float64(2.5).rint() == 2

Float64.round

Float64.round : func(x: Float64 -> Float64)

Rounds a number to the nearest whole number integer.

Return: The nearest integer value of x.

Example:

assert Float64(2.3).round() == 2
assert Float64(2.7).round() == 3

Float64.significand

Float64.significand : func(x: Float64 -> Float64)

Extracts the significand (or mantissa) of a number.

Return: The significand of x.

Example:

assert Float64(1234.567).significand() == 1.2056318359375

Float64.sin

Float64.sin : func(x: Float64 -> Float64)

Computes the sine of a number (angle in radians).

Return: The sine of x.

Example:

assert Float64(0.0).sin() == 0

Float64.sinh

Float64.sinh : func(x: Float64 -> Float64)

Computes the hyperbolic sine of a number.

Return: The hyperbolic sine of x.

Example:

assert Float64(0.0).sinh() == 0

Float64.sqrt

Float64.sqrt : func(x: Float64 -> Float64)

Computes the square root of a number.

Return: The square root of x.

Example:

assert Float64(16.0).sqrt() == 4

Float64.tan

Float64.tan : func(x: Float64 -> Float64)

Computes the tangent of a number (angle in radians).

Return: The tangent of x.

Example:

assert Float64(0.0).tan() == 0

Float64.tanh

Float64.tanh : func(x: Float64 -> Float64)

Computes the hyperbolic tangent of a number.

Return: The hyperbolic tangent of x.

Example:

assert Float64(0.0).tanh() == 0

Float64.tgamma

Float64.tgamma : func(x: Float64 -> Float64)

Computes the gamma function of a number.

Return: The gamma function of x.

Example:

assert Float64(1.0).tgamma() == 1

Float64.trunc

Float64.trunc : func(x: Float64 -> Float64)

Truncates a number to the nearest integer towards zero.

Return: The integer part of x towards zero.

Example:

assert Float64(3.7).trunc() == 3
assert Float64(-3.7).trunc() == -3

Float64.with_precision

Float64.with_precision : func(n: Float64, precision: Float64 -> Float64)

Round a number to the given precision level (specified as 10, .1, .001 etc).

Return: The number, rounded to the given precision level.

Example:

assert Float64(0.1234567).with_precision(0.01) == 0.12
assert Float64(123456.).with_precision(100) == 123500
assert Float64(1234567.).with_precision(5) == 1234565

Float64.y0

Float64.y0 : func(x: Float64 -> Float64)

Computes the Bessel function of the second kind of order 0.

Return: The Bessel function of the second kind of order 0 of x.

Example:

assert Float64(1.0).y0().near(0.08825696421567698)

Float64.y1

Float64.y1 : func(x: Float64 -> Float64)

Computes the Bessel function of the second kind of order 1.

Return: The Bessel function of the second kind of order 1 of x.

Example:

assert Float64(1.0).y1().near(-0.7812128213002887)

Int

Int.abs

Int.abs : func(x: Int -> Int)

Calculates the absolute value of an integer.

Return: The absolute value of x.

Example:

assert (-10).abs() == 10

Int.choose

Int.choose : func(n: Int, k: Int -> Int)

Computes the binomial coefficient of the given numbers (the equivalent of n choose k in combinatorics). This is equal to n.factorial()/(k.factorial() * (n-k).factorial()).

Return: The binomial coefficient, equivalent to the number of ways to uniquely choose k objects from among n objects, ignoring order.

Example:

assert 4.choose(2) == 6

Int.clamped

Int.clamped : func(x: Int, low: Int, high: Int -> Int)

Returns the given number clamped between two values so that it is within that range.

Return: The first argument clamped between the other two arguments.

Example:

assert 2.clamped(5, 10) == 5

Int.factorial

Int.factorial : func(n: Int -> Text)

Computes the factorial of an integer.

Return: The factorial of the given integer.

Example:

assert 10.factorial() == 3628800

Int.get_bit

Int.get_bit : func(i: Int, bit_index: Int -> Bool)

In the binary representation of an integer, check whether a given bit index is set to 1 or not.

For fixed-size integers, the bit index must be between 1 and the number of bits in that integer (i.e. 1-64 for Int64). For Int, the bit index must be between 1 and Int64.max. Values outside this range will produce a runtime error.

Return: Whether or not the given bit index is set to 1 in the binary representation of the integer.

Example:

assert not 6.get_bit(1)
assert 6.get_bit(2)
assert 6.get_bit(3)
assert not 6.get_bit(4)

Int.hex

Int.hex : func(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)

Converts an integer to its hexadecimal representation.

Return: The hexadecimal string representation of the integer.

Example:

assert 255.hex(digits=4, uppercase=yes, prefix=yes) == "0x00FF"

Int.is_between

Int.is_between : func(x: Int, a: Int, b: Int -> Bool)

Determines if an integer is between two numbers (inclusive).

Return: yes if a <= x and x <= b or a >= x and x >= b, otherwise no

Example:

assert 7.is_between(1, 10)
assert 7.is_between(10, 1)
assert not 7.is_between(100, 200)
assert 7.is_between(1, 7)

Int.is_prime

Int.is_prime : func(x: Int, reps: Int = 50 -> Bool)

Determines if an integer is a prime number.

This function is probabilistic. With the default arguments, the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See the GNU MP docs for more details.

Return: yes if x is a prime number, no otherwise.

Example:

assert 7.is_prime()
assert not 6.is_prime()

Int.next_prime

Int.next_prime : func(x: Int -> Int)

Finds the next prime number greater than the given integer.

This function is probabilistic, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See the GNU MP docs for more details.

Return: The next prime number greater than x.

Example:

assert 11.next_prime() == 13

Int.octal

Int.octal : func(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)

Converts an integer to its octal representation.

Return: The octal string representation of the integer.

Example:

assert 64.octal(digits=4, prefix=yes) == "0o0100"

Int.onward

Int.onward : func(first: Int, step: Int = 1 -> Text)

Return an iterator that counts infinitely from the starting integer (with an optional step size).

Return: An iterator function that counts onward from the starting integer.

Example:

nums : &[Int] = &[]
for i in 5.onward()
    nums.insert(i)
    break if i == 10
assert nums[] == [5, 6, 7, 8, 9, 10]

Int.parse

Int.parse : func(text: Text, base: Int? = none, remainder: &Text? = none -> Int?)

Converts a text representation of an integer into an integer.

Return: The integer represented by the text. If the given text contains a value outside of the representable range or if the entire text can't be parsed as an integer, none will be returned.

Example:

assert Int.parse("123") == 123
assert Int.parse("0xFF") == 255
assert Int.parse("123xyz") == none
remainder : Text
assert Int.parse("123xyz", remainder=&remainder) == 123
assert remainder == "xyz"

# Can't parse:
assert Int.parse("asdf") == none

# Outside valid range:
assert Int8.parse("9999999") == none

# Explicitly specifying base:
assert Int.parse("10", base=16) == 16

Int.sqrt

Int.sqrt : func(x: Int -> Int)

Calculates the nearest square root of an integer.

Return: The integer part of the square root of x.

Example:

assert 16.sqrt() == 4
assert 17.sqrt() == 4

Int.to

Int.to : func(first: Int, last: Int, step: Int? = none -> func(->Int?))

Returns an iterator function that iterates over the range of numbers specified.

Return: An iterator function that returns each integer in the given range (inclusive).

Example:

iter := 2.to(5)
assert iter() == 2
assert iter() == 3
assert iter() == 4
assert iter() == 5
assert iter() == none

assert [x for x in 2.to(5)] == [2, 3, 4, 5]
assert [x for x in 5.to(2)] == [5, 4, 3, 2]
assert [x for x in 2.to(5, step=2)] == [2, 4]

List

List.binary_search

List.binary_search : func(list: [T], predicate: func(x:T->Bool) -> Int)

Performs a binary search on a sorted list.

Return: Find the first item in the list where the predicate function is true and return its index (or none if no such item exists). This assumes that the predicate function is monotonic over the list's contents. In other words, the predicate is false for the first zero or more items in the list and then true for the remainder of the list.

Example:

# Find an item:
assert [10, 20, 30, 40].binary_search(func(x:Int) x == 30) == 3
# No such item:
assert [10, 20, 30, 40].binary_search(func(x:Int) x == 25) == none
# Find an insertion point (where an item would go to preserve sort order):
assert [10, 20, 30, 40].binary_search(func(x:Int) x >= 25) == 3

List.by

List.by : func(list: [T], step: Int -> [T])

Creates a new list with elements spaced by the specified step value.

Return: A new list with every step-th element from the original list.

Example:

assert [1, 2, 3, 4, 5, 6].by(2) == [1, 3, 5]

List.clear

List.clear : func(list: @[T] -> Void)

Clears all elements from the list.

Return: Nothing.

Example:

list := &[10, 20]
list.clear()
assert list[] == []

List.counts

List.counts : func(list: [T] -> {T=Int})

Counts the occurrences of each element in the list.

Return: A table mapping each element to its count.

Example:

assert [10, 20, 30, 30, 30].counts() == {10:1, 20:1, 30:3}

List.find

List.find : func(list: [T], target: T -> Int?)

Finds the index of the first occurrence of an element (if any).

Return: The index of the first occurrence or none if not found.

Example:

assert [10, 20, 30, 40, 50].find(20) == 2
assert [10, 20, 30, 40, 50].find(9999) == none

List.from

List.from : func(list: [T], first: Int -> [T])

Returns a slice of the list starting from a specified index.

Return: A new list starting from the specified index.

Example:

assert [10, 20, 30, 40, 50].from(3) == [30, 40, 50]

List.has

List.has : func(list: [T], target: T -> Bool)

Checks if the list has an element.

Return: yes if the list has the element, no otherwise.

Example:

assert [10, 20, 30].has(20)

List.heap_pop

List.heap_pop : func(list: @[T], by: func(x,y:T->Int32) = T.compare -> T?)

Removes and returns the top element of a heap or none if the list is empty. By default, this is the minimum value in the heap.

Return: The removed top element of the heap or none if the list is empty.

Example:

my_heap := &[30, 10, 20]
my_heap.heapify()
assert my_heap.heap_pop() == 10

List.heap_push

List.heap_push : func(list: @[T], item: T, by = T.compare -> Void)

Adds an element to the heap and maintains the heap property. By default, this is a minimum heap.

Return: Nothing.

Example:

my_heap : &[Int]
my_heap.heap_push(10)
assert my_heap.heap_pop() == 10

List.heapify

List.heapify : func(list: @[T], by: func(x,y:T->Int32) = T.compare -> Void)

Converts a list into a heap.

Return: Nothing.

Example:

my_heap := &[30, 10, 20]
my_heap.heapify()

List.insert

List.insert : func(list: @[T], item: T, at: Int = 0 -> Void)

Inserts an element at a specified position in the list.

Since indices are 1-indexed and negative indices mean "starting from the back", an index of 0 means "after the last item".

Return: Nothing.

Example:

list := &[10, 20]
list.insert(30)
assert list == [10, 20, 30]

list.insert(999, at=2)
assert list == [10, 999, 20, 30]

List.insert_all

List.insert_all : func(list: @[T], items: [T], at: Int = 0 -> Void)

Inserts a list of items at a specified position in the list.

Since indices are 1-indexed and negative indices mean "starting from the back", an index of 0 means "after the last item".