Library core
This is the core library, which means you usually don't need to import it.
The Toit core library.
This library is automatically imported into every Toit program.
Exported interfaces
A container specialized for bytes.
A collection of elements.
A task.
Exported classes
A Boolean value.
A double-ended queue.
A Duration, capturing relative times.
The class of
false.A 64 bit floating point value.
A map that uses object identity instead of the == operator to test equality of keys. This map still uses the hash-code method on keys (see Map). There is no identity hash code operation on arbitrary classes in Toit.
A set that uses object identity instead of the == operator to test equality of elements. This set still uses the hash-code method on elements (see Set). There is no identity hash code operation on arbitrary classes in Toit.
A 64 bit integer.
A lambda, or closure.
A linear collection of objects.
A map from key objects to values.
A number.
A base class for all classes.
Simplistic profiler based on bytecode invocation counts.
A set of keys.
A Unicode text object.
A wall clock time.
The class of
true.Exported globals
Assertion failed error.
Thrown when an assertion fails both by the 'assert:' language construct and by other assertion checking libraries.
Cancelled error.
Deadline exceeded error.
The number of bytes per kilobyte.
Deprecated: Use system.LINE-TERMINATOR instead.
The number of bytes per megabyte.
Deprecated: Use system.PLATFORM-FREERTOS instead.
Deprecated: Use system.PLATFORM-LINUX instead.
Deprecated: Use system.PLATFORM-MACOS instead.
Deprecated: Use system.PLATFORM-WINDOWS instead.
Deprecated: Use system.STATS-INDEX-ALLOCATED-MEMORY instead.
Deprecated: Use system.STATS-INDEX-BYTES-ALLOCATED-IN-OBJECT-HEAP instead.
Deprecated: Use system.STATS-INDEX-FULL-COMPACTING-GC-COUNT instead.
Deprecated: Use system.STATS-INDEX-FULL-GC-COUNT instead.
Deprecated: Use system.STATS-INDEX-GC-COUNT instead.
Deprecated: Use system.STATS-INDEX-GROUP-ID instead.
Deprecated: Use system.STATS-INDEX-PROCESS-ID instead.
Deprecated: Use system.STATS-INDEX-PROCESS-MESSAGE-COUNT instead.
Deprecated: Use system.STATS-INDEX-RESERVED-MEMORY instead.
Deprecated: Use system.STATS-INDEX-SYSTEM-FREE-MEMORY instead.
Deprecated: Use system.STATS-INDEX-SYSTEM-LARGEST-FREE instead.
Exported functions
Registers the given lambda as a finalizer for the object.
Calls the finalizer if all references to the object are lost. (See limitations below).
Errors
It is an error to assign a finalizer to a smi or an instance that already has a finalizer (see remove-finalizer).
It is also an error to assign null as a finalizer.
Warning
Misuse of this API can lead to undefined behavior that is hard to debug.
Advanced
Finalizers are not automatically called when a program exits. This is also true for objects that weren't reachable anymore before the program exited.
An arbitrary amount of time may pass from the object becomes unreachable and the finalizer is called.
Returns information about who build this application snapshot.
Returns the Toit SDK version that generated this application snapshot.
If an exception is thrown during the block call, then the trace is printed if the trace is true (and the trace can otherwise be printed).
If an exception is thrown during the block call, then unwinding continues if the unwind is true.
If an exception is thrown during the block call, then the trace is printed if the trace is true (and the trace can otherwise be printed).
If an exception is thrown during the block call, then unwinding continues if the unwind is true.
Catches exceptions thrown in the given block.
Returns null if the call to the block completes without exception.
Returns the thrown exception if an exception is thrown during the call of the block and unwind returns a falsy value (see below).
The trace block decides whether the trace should be printed in case an exception has been thrown. The trace block is called with the thrown exception and the trace (
trace.call exception trace) and should return a boolean. If the trace call returns true, then the trace is printed. However, the trace can only be printed if there is a trace and this task hasn't been cancelled.The unwind block decides whether unwinding should continue in case of a caught exception. The unwind block is called with the thrown exception and the trace (
unwind.call exception trace) and should return a boolean value. If unwind call returns true, then unwinding continues.Returns the number of initial zeros in binary representation of the argument.
The argument is treated as an unsigned 64 bit number. Thus it returns 0 if given a negative input.
Creates an off-heap byte array with the given size.
Off-heap byte arrays are preferred when transferring data between applications.
Enters and calls the given critical block.
Within block, the current task won't be interrupted by cancellation exceptions. Instead such exceptions will be delayed until the block is left. The critical block can be interrupted by a timeout (see with-timeout) if respect-deadline is true.
Prints the given object for debugging.
Does not yield the currently running task.
Prints an empty line for debugging.
Does not yield the currently running task.
Exits the VM with the given status.
Argument $status
0 signals a successful exit. All other statuses are error codes.
Converts a hex digit character char in the ranges '0'-'9', 'a'-'f', or 'A'-'F'.
Returns the value between 0 and 15.
Calls the block if-error on invalid input and returns its return value if any.
Converts a hex digit character in the ranges '0'-'9', 'a'-'f', or 'A'-'F'.
Returns the value between 0 and 15.
The input must be a valid hex digit character.
Whether x and y are identical objects.
Every object is identical to itself.
For numbers, two objects are furthermore identical if they have the same numeric value. Contrary to
== two numbers must be of the same type, and have the same bit-pattern. As such, -0.0 == 0.0, but not identical -0.0 0.0.Two strings are identical if they contain the same characters. For example, we have
identical "tw" + "in" "twin".For floats, two NaN's (not-a-number) are identical when they have the same bits. For example, we have
identical float.NAN float.NAN, but not identical float.NAN (float.from-bits float.NAN.bits + 1). This is unlike == where NaN's are never equal, so float.NAN == float.NAN is always false.Returns the max of a and b.
Returns a if a and b are equal.
Returns the min of a and b.
Returns a if a and b are equal.
Prints the message.
Prints an empty line.
This function is generally used to improve the output of the console output, but may have no effect on other receivers of the print message.
Deprecated.
Deprecated.
Deprecated: Use system.process-stats instead.
Deprecated: Use system.process-stats instead.
Returns the name of the toit file, image, or snapshot that the current program was run from. May return null if this information is not available.
Returns a random number in the range [0..0xFFF_FFFF] (inclusive).
The returned number is the result of a PRNG (pseudo random number generator). The seed of the PRNG can be changed by calling set-random-seed.
Returns a random number in the range [0..n[ (n exclusive).
The returned number is the result of a PRNG (pseudo random number generator). The seed of the PRNG can be changed by calling set-random-seed.
Unregisters the finalizer registered for object.
Returns whether the object had a finalizer.
Rethrows the given exception along with the trace.
Rounds a non-negative value down to the previous multiple of the divisor.
Examples
round-down 27 10 // => 20
round-down 7 2 // => 6
round-down -13 10 // => OUT_OF_RANGE error
Rounds a non-negative value up to the next multiple of the divisor.
Examples
round-up 17 10 // => 20
round-up 7 2 // => 8
round-up -13 10 // => OUT_OF_RANGE error
Seeds the random number generator with the seed.
Currently only the first 16 bytes of the seed are used.
Stores the given rules in the
TZ environment variable and calls tzset, thus activating it.Valid TZ values can be easily obtained by looking at the last line of the zoneinfo files on Linux machines:
tail -n1 /usr/share/zoneinfo/Europe/Copenhagen
Examples
set-timezone "CET-1CEST,M3.5.0,M10.5.0/3" // Central European Timezone (as of 2024).
set-timezone "PST8PDT,M3.2.0,M11.1.0" // Pacific Time (as of 2024).
Spawns a new process that starts executing the given lambda.
The new process does not share any memory with the spawning process. If the lambda captures variables, those are copied to the new process.
May throw if the captured variables can't be serialized.
Returns the object for the current task.
Creates a new user task.
Calls code in a new task.
If the background flag is set, then the new task will not block termination. The background task flag is passed on to sub-tasks.
Throws the given exception.
Unwinds the stack of this task calling associated finally-blocks. By default, a task with an exception will print the stack trace and terminate the task.
Converts a number between 0 and 15 to a lower case hex digit.
Converts a number between 0 and 15 to an upper case hex digit.
Marks code point as unreachable.
Must not be reached in the program.
Returns information about who built this virtual machine.
Returns the Toit SDK model that this virtual machine has been built from.
Returns the Toit SDK version that this virtual machine has been built from.
Calls the given block but throws an exception if the timeout is exceeded.
If timeout is null, calls the block without a timeout.
Calls the given block but throws an exception if a timeout of ms milliseconds is exceeded.
Calls the given block but throws an exception if a timeout of us microseconds is exceeded.
Voluntarily yields control of the CPU to other tasks.
Advanced
The Toit programming language is cooperatively scheduled, so it is important to place yields in long running loops if other tasks should get an opportunity to run.