Standard Library

Standard Library

API for interfacing with C

Functions

Function have no return values. They must be declared as procedures. Parameter qualified as in are passed as value. Parameter out are passed as pointer. References are equivalent to pointers in C. An out reference is passed as a pointer to a pointer.

The gemstone function

type box: book {
    ref half half int: title
}

fun foo(in int: a, in book: b)(out int: c, out ref book: d)

Can be resolved to the following C code:

struct book {
    char* title;
}

void foo(int a, struct book b, int* c, struct book** d);

Modules of standard library

• core
• bool
• mem
• math
• vec
• str
• os
• io
• fs
• net

Module core

Provides core data types and functionality for other standard library modules

Extended type defintions for interoperability

# single byte (8-Bit)
type unsigned half half int: byte

# single word (16-Bit)
type unsgined double byte: word

# double word (32-Bit)
type unsgined double word: dword

# quad word (64-Bit)
type unsgined double dword: qword

# IEEE-754 single precision
type signed float: f32

# IEEE-754 double precision
type signed double f32: f64

Module bool

type byte: bool

bool: True = 1
bool: False = 0

Module mem

Interface for heap memory management.

Global Variables

ref byte: NULL = 0 as ref byte

Allocate memory

Return a pointer to a location of heap memory which is at least n bytes in size.

fun alloc(in dword: n)(out ref byte: ptr)

Reallocate memory

Return a pointer to a location of heap memory which is at least n bytes in size. If possible extend the area of the given pointer to n bytes. If not possible, ptr will be a new pointer to a slice with at least n bytes of capacity.

fun realloc(in dword: n)(in out ref byte: ptr)

C declaration:

void mem_realloc(int32_t n, (unsigned char*)* ptr);

Free memory

Free the given block of memory

fun free(in ref byte: ptr)

Copy memory

Copy n bytes from src into dst.

fun copy(in ref byte: src, in ref byte dst, in dword n)

Fill memory

Copy pattern n times into dst.

fun copy(in ref byte dst, in byte: pattern, in dword n)

Copy slice

fun copy_slice(in ref bytes: src, in ref byte: dst)(in dword: src_s)(in dword: dst_s)(in dword: n)

Module math

Globals

f32: PI = 3.141592653589793
f32: E = 2.718281828459045

Functions

fun sin(in f32)(out f32)
fun cos(in f32)(out f32)
fun tan(in f32)(out f32)
fun floor(in f32)(out f32)
fun fract(in f32)(out f32)

Module vec

Provides a growable vector data type

import "mem"

silent dword: PRE_ALLOC_BYTES = 16

type box: Vec {
    silent ref byte: array
    silent dword: len
    silent dword: cap

    silent fun resize(in dword: n) {
        self.cap = self.cap + n + PRE_ALLOC_BYTES
        realloc(self.cap)(self.array)
    }

    silent fun shrink(in dword: n) {
        self.cap = self.cap - n
        realloc(self.cap)(self.array)
    }

    fun push(in ref byte: bytes, in dword n) {
        if self.len + n > cap {
            self.resize(self.len + n - cap)
        }

        copy_slice(self.array, bytes)(self.len, 0)(n)

        self.len = len + bytes
    }

    fun pop(in dword: n, out ref byte: bytes) {
        
        copy_slice(bytes, self.array)(0, self.len - n)(n)

        self.shrink(n)
    }

    fn get(in dword: idx)(out ref byte: ptr) {
        ptr = self.array + idx
    }
}

Module str

Provides a string box and manioulation functions

type byte: utf8
type byte: ascii

# UTF-8 encoded growable string
type box: String {
    silent Vec: bytes

    fun from_raw(in ref byte: raw_utf8, in dword: len)
    fun clone(in ref String: other)
    fun concat(in ref String other)
    fun contains(in ref String other)(out bool: res)
    fun starts_with(in ref String other)(out bool: res)
    fun ends_with(in ref String other)(out bool: res)
}

Module os

Provides cross platform os related functionality.

Get name/identifier of OS

fun platform_name(out ref utf8: name)

Environment variables

Get environment variable

fun get_env(in ref utf8: name)(out ref utf8: value)

Set environment variable

fun set_env(in ref utf8: name)(in ref utf8: value)

Program arguments

Get number of arguments

fun get_arg_count(out dword: idx)

Get argument

fun get_arg(in dword: idx)(out ref utf8: value)

Module io

Low level entry point for platform specific I/O resources which may permit read/write and auxilery operations.

# platform specific handle for an I/O resource
type dword: handle

Read

fun read(in handle: device, in dword: n)(out ref byte: ptr)

Write

fun write(in handle: device, in dword: n, in ref byte: ptr)

Flush

fun flush(in handle: device)

Standard I/O

fun get_stdout_handle(out handle: device)

fun get_stderr_handle(out handle: device)

fun get_stdin_handle(out handle: device)

Module fs

Provides a cross platform abstraction layer for basic file interactions.

# File path
type box: Path {
    silent String: buf
    silent utf8: path_separator

    fun from_string(in ref String: path)
    fun append(in String: elem)
    fun remove(in dword: idx)
    fun exists(out bool: exists)
    fun open(out File: file)
    fun separator(out utf8: sep)
    fun set_separator(in utf8: sep)
}

# Abstraction of a file
type box: File {
    silent handle: os_device_handle
    silent Path: path

    fun write(in ref byte: bytes, in dword: n)
    fun write_string(in ref String: string)

    fun read(in ref byte: bytes, in dword: n)
    fun read_string(out String: content)
    fun read_line(out String: line)

    fun name()
    fun rename(in String: new_name)

    fun delete()
    fun move()

    fun close()
}

Module net

Simple functionality for TCP/IP UDP/IP networking