docs.std

This the documentation of smoλ's standard library. It is automatically kept up to date by periodically running the following command. That pulls from code annotations and overloaded implementations.

./smol docs/std.s --task doc

std.builtins

std/builtins.s

std.builtins.convert unsafe

Standard library wrapping and simplification of C console commands.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

read

Reads several string and primitive types from console text input given by the user; they need to press enter after entering the input. String reading is restricted to 1024 bytes allocated on the heap. You can have more control of string reading on alternatives. Non-string variations of this method are restricted to local variables. Invalid inputs create service failures.

convert

std.builtins.err unsafe

Standard library implementations of error utilities.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

ok

Checks if an error code corresponds to no error. If it does not, the service fails while printing the type of error. Error codes can be user errors, buffer errors, unknown errors, or no errors.

assert

print

Prints an interpretation of the error code. Error codes can be user errors, buffer errors, unknown errors, or no errors.

fail

Causes the current service to fail given a String message. This creates a user error code.

std.builtins.num unsafe

Standard library wrapping of C basic arithmetics and printing.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

not

Negation of a boolean. In general, for unary operations, there is NO equivalent operator to overload. This promotes a currying-based notation for manipulating single values.

Here is a simple example, though this is often used in conditional statements:

print(true:not)

exists

Checks if a pointer is non-null. Pointer access and manipulation is inherently unsafe and you should not encounter that in normal code writing. For those aiming to extend the standard library or who dabble with inherently unsafe use cases, this can be used to check for memory allocation failures and trigger a service failure to safely collapse the current execution state.

print

Prints a primitive number, character, or boolean to the console.

printin

Prints a primitive number, character, or boolean to the console without changing line.

le

Checks if the first number is less than or equal to the second and overloads the corresponding operator. Only the same number types can be compared, and explicit casts are required otherwise.

Here is an example demonstrating the need to use an f64 zero (0.0 and not 0) to compare with another read value of the same type:

x=f64:read
if x<0.0 -> print("negative")
else -> print("non-negative")

ge

Checks if the first number is greater than or equal to the second and overloads the corresponding operator. Only the same number types can be compared, and explicit casts are required otherwise.

Here is an example demonstrating the need to use an f64 zero (0.0 and not 0) to compare with another read value of the same type:

x=f64:read
if x>0.0 -> print("positive")
else -> print("non-positive")

lt

Checks if the first number is less than the second and overloads the corresponding operator.

Here is an example:

print(1>=2)

gt

Checks if the first number is greater than the second and overloads the corresponding operator.

Here is an example:

print(1>=2)

leq

Checks if the first number is less than or equal to the second.

geq

Checks if the first number is greater than or equal to the second.

eq

Checks if two primitives are equal and overloads the corresponding operator. Equality can be checked for all primitives, and is defined for other runtypes too in the standard library, such as strings.

Here is an example:

print(1==2)

neq

Checks if two primitives are not equal and overloads the corresponding operator. Non-equality can be checked for all primitives, and is defined for other runtypes too in the standard library, such as strings.

Here is an example:

print(1!=2)

add

Addition of two numbers of the same type and overloads the corresponding operator.

Here is an example:

print(1+2)

mod

Modulo operation for signed or unsigned integers. For i64, only positive divisors are allowed. Fails on zero divisor. Overloads the corresponding operator. Here is an example:

print(1%2)

sub

Subtraction of two numbers of the same type. Doing so for u64 will create a service failure if the result would be negative. Overloads the corresponding operator for numbers.

Here is an example that FAILS because the default integer type is u64:

print(1-2)

mul

Multiplication of two numbers of the same type and overloads the corresponding operator.

Here is an example:

print(3*2)

div

Division of two numbers of the same type. Division by zero for i64 or u64 creates a service failure, but for f64 it yields NaN. Overloads the corresponding operator. Here is an example that yields zero by performing integer division:

print(1/2)

negative

Returns the additive inverse (negation) of an i64 or f64. Does NOT overload any operation. Having u64 as the default type helps avoid many spurious negation errors, especially when memory handling is concerned.

Both examples below print -1:

print(0:i64-1:i64)
print(1:i64:negative)

std.builtins.range

Standard library implementation of u64 ranges.

next

Obtains the next element in the range. Using a combination of a range and next element traversal is safer than manually checking bounds.

Below is the main usage pattern. Notice that next's argument is an in-place constructed u64 number that is mutable to obtain the next value. The function progress the range's state and set that value.

range(10)
:while next(u64 &i)
    print(i)
    --

range

Defines a u64 range as a structural type (instead of nominal type). When directly using variables as ranges, the position should be mutable. A couple of calling conventions are provided for default values of 0 for start and 1 for step.

std.builtins.str unsafe

Standard library implementation of the extensible string model based on C pointers and an implementation for const char arrays.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

next

Retrieves the next element over a Split string iteration. Example: Split('I like bananas', ' '):while next(str& word) print(word) --

String

A union between str, nstr, and constant strings cstr. Constant strings are those that generated by default when enclosing some text in quotients and are stored in the program memory.

Main usage is to abstract an argument's type by converting it to str. The conversion is a zero cost abstraction in that needless operations will be removed. But it still augments constant strings with length and first element inform if these are needed. Here is an example:

smo foo(String _s)
    s = _s:str
    ...
    --

IndependentString

A copy of the String union that can be used when a second argument is needed for a string of a potentially different variation.

CString

A union between nstr and constant strings cstr.

Main usage is to abstract an argument's type by converting it to nstr. The conversion is a zero cost abstraction in that needless operations will be removed. But it still augments constant strings with length and first element inform if these are needed. Here is an example:

smo foo(CString _s)
    s = _s:nstr
    ...
    --

is

Compile-time check of a String exact type matching compared to an arbitrary type.
Example usage: smo foo(String s) with s:is(str) ... -- else ...----

print

Prints strings or bools to the console.

str

A memory allocated string and converters from constant strings and booleans to the type. Other standard library implementations provide more converters.

nstr

A null-terminated variation of str. Many operation produce this string version, as it can be readily converted to str at no cost (for the inverse, you need to copy the string)

printin

Prints strings or bools to the console without evoking a new line at the end.

eq

neq

slice

strip

len

at

Split

Splits a String given a query String. Optionally, you may also provide a starting position, where the default is 0. The result of the split can be iterated through with next. This does not allocate memory in that a substring is retrieved, so you might consider copying the splits - or store them on data structures like maps that automatically copy data if needed.

std.file unsafe

Standard library implementation of file management that uses the C filesystem.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

to_end

Go to the end of a WriteFile. This is not implemented for ReadFile, as it makes more sense to just close the latter. Returns a boolean indicating a successful operation.

ReadFile

An opened file that is meant to be read only.

WriteFile

An opened file that is meant to be read or write.

console

open

Opens a File given a String path, in which case you might get service failure due to external factors. Opening a WriteFile, may also cause service failure if the file already exists - in that case remove it first. On the other hand, a ReadFile must already exist to be opened.

next_line

Reads the next line of a file while using it as an iterator. It accomodates Arena and Volatile memories.

Here is an example where volatile memory is used to avoid repeated or large allocations:

endl="n":str.first // optimized to just setting the new line character
on Heap:volatile(1024)
    ReadFile("README.md")
    :open("README.md")
    :while next_line(str& line)
        if line[line:len-1]==endl
             line = line[0 to line:len-1]
             --
        print(line)
    ----

next_chunk

Reads the next chunk of a file while using it as an iterator. It accomodates Arena and Volatile memories.

Here is an example where volatile memory is used to avoid repeated or large allocations:

on Heap:volatile(1024)
    ReadFile
    :open("README.md")
    :while next_chunk(str& chunk)
        print(chunk)
    ----

File

A union between file types that allows common reading and positioning operations.

to_start

Go to the beginning of a File. You can continue read or writing from there. May cause service failure due to external factors.

write

Writes a string on a WriteFile.

len

Computes the size of a File in bytes.

ended

Checks if the ending of the file has been reached. This is normal to be true for WriteFile.

is_file

Checks if a String path is a file system file.

is_dir

Checks if a String path is a file system directory.

remove_file

Deletes a file from the system. May cause service failure due to external factors or if the file is already open.

create_dir

Creates a directory given a String path. May cause service failure due to external factors or if the directory already exists.

std.map

std/map.s

std.math unsafe

Standard library wrapping of C math operations.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

cos

acos

sin

asin

exp

pi

tan

atan

atan2

is_nan

is_inf

sqrt

pow

log

std.mem

std/mem.s

std.mem.arena unsafe

Standard library implementation of arena allocation, marked as @noborrow but unsafely returned from constructors. Pointer arithmetics yield offsets within arenas.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

Dynamic

Arena

read

Volatile

controlled_corrupt

allocate

is

DerivedMemory

dynamic

used

len

Memory

BoundedMemory

arena

volatile

std.mem.device unsafe

Standard library implementation of memory management that accounts for the stack and heap and depends on the runtime.h implementation of heap memory, and GCC implementation of alloca. Stack alloactions cannot be returned from services, as the stack is pruned when programming function calls end. Smo runtypes are not implemented as functions, so it is fine to return stack allocations from them.

This file is marked with the unsafe keyword. This means that its internal implementation (only) could be subject to bugs that the language's design otherwise eliminates. By using this file as a direct or indirect dependency you are trusting its implementation. Given this trust, consider other non-unsafe files using it as safe.

Stack

Represents call stack memory. Allocating on this is near-zero cost by being just an arithmetic addition but its total size is limited - typically up to a few megabytes. Prefer this for small localized data that need to be processed exceedingly fast.

Heap

Random access memory (RAM) that can be allocated with __runtime_alloc. Writing to it and reading from it can be slow for programs that keep. Modern processors optimize heap usage by prefetching and caching nearby areas as the ones you access. For this reason, prefer creating Arena regions when you have a sense of the exact amount of data you will need. Allocating on the heap can leak memory under certain conditions, but the lnaguage's safety mechanism prevents this. Use other allocators in those cases. The standard library provides a Dynamic type that also accesses several heap allocations, though with an additional level of indirection.

MemoryDevice

Refers to either stack or heap memory.

ContiguousMemory

Represents allocated memory management. It keeps track of both currently used pointer addresses, for example if these are offsets of allocated base pointers with finally segments calling __runtime_free on those, and the underlying pointer addresses. Importantly, not all this information is retained after compilation, as most of it -perhaps all- is optimized away. But this structure still helps the compiler organize where to place memory releases, if needed. Users of the standard library will not generally work with this type, as it is highly unsafe to get its pointer fields and requires annotation for the language to allow that.

allocate

Allocates memory on a predetermined device given a number of entries and an optional primitive data type. If the data type is not provided, char is assumed so that the number of entries becomes equal to the number of allocated bytes. Other standard library overloads implement allocation for more memory types, derived from the devices. Allocations throughout the standard library track the raw allocated memory so that usage is finally released only when the last dependent variable (e.g., the last string allocated on a heap arena) is no longer used. See ContiguousMemory.

is

__unsafe_put

Can modify an allocated memory. This operation cannot be callsed in safe files.

at

Accesses a specific memory position of the corresponding base type. This operation includes bound checks.

std.mem.grid

std/mem/grid.s

MemoryGrid