Contents

docs.std 🔝

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

@import std.core -> Number

std.core 🔝

std.core.convert unsafe 🔝

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 the console. The user needs to press enter after entering the input. Invalid inputs create service failures, including in the case where the number is too large to properly process. Example:

printin("Give a number.")
x = f64.read
printin("Rounded.")
print(i64(x+0.5))

convert 🔝

Converts a String representation to various numeric formats. This is lightweight and does not consume additional memory. The current service fails if the conversion is not possible. Example:

x = f64.convert("1.2")
print(x)

std.core.err unsafe 🔝

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.

assert_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 a string interpretation of an error code.

fail 🔝

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

printin("Give a number.")
x = i64.read()
if x==0.0
    return fail("Cannot compute the inverse of zero")
printin("Its inverse is.")
print(1.0/x)

std.core.num unsafe 🔝

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 🔝

not 🔝

Negation of a boolean. There is no equivalent operator, and currying-based notation should be used 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. 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
    return print("negative")
else
    return 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. 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
    return print("positive")
else
    return print("non-positive")

lt 🔝

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

print(1>=2)

gt 🔝

Checks if the first number is greater than the second and overloads the corresponding operator. 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 also defined for other types in the standard library, such as strings. 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 also defined for other types in the standard library, such as strings. Example:

print(1!=2)

add 🔝

Addition of two numbers of the same type and overloads the corresponding operator. 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. 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. 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.core.range 🔝

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 sets the next value, progresses the range's state, and returns whether the iteration ended. The first retrieved value is the starting element of the range. Example:

range(10)
.while next(@mut u64 i)
    then 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.core.str unsafe 🔝

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(@mut str word)
    then print(word)

key 🔝

getch 🔝

is_left 🔝

is_right 🔝

is_up 🔝

is_down 🔝

is_tab 🔝

is_delete 🔝

is_backspace 🔝

is_char 🔝

to_char 🔝

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:

def foo(CString _s)
    s = _s.nstr()
    ...
    end

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:

def foo(String _s)
    s = _s.str()
    ...
    end

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.

is 🔝

Compile-time check of a String exact type matching compared to an arbitrary type.
Example usage.

def foo(String s)
    with s.is(str)
        ...
        end else
        ...
    end end

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 🔝

Checks for equality between String types when considering their contents. Implementation of this operation varies, ensuring that the cached first element of strings (not available for cstr) is compared first and then the lengths are taken into account to compare memory bytes. Example:

if "me"=="me" return print("me!")

neq 🔝

Equivalent to logical inversion of String eq. It is faster to write and run.

slice 🔝

Obtains a substring slice out of a String. This always produces a str results, because null termination cannot be guaranteed for most results - and is dropped even if it could be guaranteed to save computations.

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 🔝

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 written.

console 🔝

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(@mut str chunk)
    then print(chunk)

open 🔝

Opens a File given a String path. There might be service failure due to external factors. Opening a WriteFile, may also cause failure if it already exists - in that case remove it first and it will be created. On the other hand, a ReadFile must already exist to be opened. Files must be set as mutable variables to allow reads and writes. Otherwise, only a few operations become available. Example for overwriting a file:

if is_file("hi.txt")
    then remove_file("hi.txt")
@mut file = WriteFile.open("tmp.txt")
file:print("Hello world!")
@release file // early release closes the file

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(@mut str line)
    if line[line:len-1]==endl
         then line = line[0 to line:len-1]
    then print(line)

File 🔝

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

print 🔝

Writes a string on a WriteFile.

to_start 🔝

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

temp 🔝

Creates a WriteFile of a given size that is constrained to fixed memory provided by a Memory allocator. Due to safety mechanisms provided by operating systems, operations on this file may be slower than simple memory read and writes. If the operating system does not properly support memory mapped files, this may even end up consuming disk storage space of up to the given size by being stored as a temporary file. In general, reads and writes (with print) will be at most as slow as a normal file, with the contract that data cannot be recovered after termination. Some operating systems require manual deletion of temporary file folders if systems are abruptly powered off. This type of file should be mostly used to store temporary data or for testing purposes. Example usage:

on Heap.dynamic() // allocator for the file
@mut f = WrteFile.temp(1024)
f.print("hello from withing a temp file!")
f.to_start()
f.next_line(@mut u64 line)
print(line)

len 🔝

Computes the size of a File in bytes. This tries to leverage operating system metadata first, but if it fails it explicitly reads through the file once.

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.math unsafe 🔝

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.arena unsafe 🔝

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.

Region 🔝

read 🔝

Arena 🔝

Circular 🔝

Dynamic 🔝

clear 🔝

BoundMemory 🔝

Buffer 🔝

is 🔝

allocate 🔝

dynamic 🔝

used 🔝

Memory 🔝

fixed 🔝

arena 🔝

circular 🔝

len 🔝

std.mem.device unsafe 🔝

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 language'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.

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.

file_end 🔝

MemoryDevice 🔝

Refers to either stack or heap memory.

allocate 🔝

Allocates memory on a predetermined device given a number of entries. 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.

std.mem.grid 🔝

std.mem.str unsafe 🔝

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.

copy 🔝

Copies a string on a given Memory allocator. The result is nstr, that is, a string variation is null-terminated. This operation may fail if the allocation fails.

str 🔝

Provides methods for converting numbers to strings that are stored on provided Memory allocators. The result is a null-terminated nstr.

nstr 🔝