bux-lang/docs/Stdlib.md

Bux Standard Library

The Bux standard library provides core functionality for systems programming. All modules are merged into every compilation, so no explicit linking is needed.

---

Std::Io

Basic I/O and file operations wrapping C stdio.

Functions

Function	Signature	Description
PrintLine	func PrintLine(s: String)	Print string with newline
Print	func Print(s: String)	Print string without newline
PrintInt	func PrintInt(n: int)	Print integer
PrintFloat	func PrintFloat(f: float64)	Print float
PrintBool	func PrintBool(b: bool)	Print boolean
ReadLine	func ReadLine() -> String	Read line from stdin
ReadFile	func ReadFile(path: String) -> String	Read entire file into string
WriteFile	func WriteFile(path: String, content: String) -> bool	Write string to file
FileExists	func FileExists(path: String) -> bool	Check if file exists

---

Std::Fs

File system operations beyond basic I/O.

Function	Signature	Description
DirExists	func DirExists(path: String) -> bool	Check if directory exists
Mkdir	func Mkdir(path: String) -> bool	Create directory (and parents if needed)
ListDir	func ListDir(dir: String, ext: String, count: *int) -> *String	List files matching extension

Example

import Std::Fs::{DirExists, Mkdir, ListDir};

func Main() -> int {
    if DirExists("/tmp") {
        PrintLine("/tmp exists");
    }
    Mkdir("build/output");
    var count: int = 0;
    let files: *String = ListDir("src", ".bux", &count);
    return 0;
}

Example

import Std::Io::{PrintLine, ReadFile, WriteFile};

func Main() -> int {
    WriteFile("/tmp/test.txt", "Hello, Bux!");
    PrintLine(ReadFile("/tmp/test.txt"));
    return 0;
}

---

Std::Array

Fully generic dynamic array Array<T>.

Types

struct Array<T> {
    data: *T,
    len: uint,
    cap: uint,
}

Functions

Function	Signature	Description
Array_New<T>	func Array_New<T>(cap: uint) -> Array<T>	Create new array
Array_Push<T>	func Array_Push<T>(arr: *Array<T>, value: T)	Append element
Array_Pop<T>	func Array_Pop<T>(arr: *Array<T>) -> T	Remove and return last element
Array_Contains<T>	func Array_Contains<T>(arr: *Array<T>, value: T) -> bool	Linear search for value
Array_IndexOf<T>	func Array_IndexOf<T>(arr: *Array<T>, value: T) -> int	First index or -1
Array_Extend<T>	func Array_Extend<T>(arr: *Array<T>, other: *Array<T>)	Append all from other
Array_RemoveAt<T>	func Array_RemoveAt<T>(arr: *Array<T>, index: uint) -> T	Remove at index (shift left)
Array_Insert<T>	func Array_Insert<T>(arr: *Array<T>, index: uint, value: T)	Insert at index (0..=len)
Array_SwapRemove<T>	func Array_SwapRemove<T>(arr: *Array<T>, index: uint) -> T	O(1) remove (swap with last)
Array_Clone<T>	func Array_Clone<T>(arr: *Array<T>) -> Array<T>	Shallow clone (value copy)
Array_Reverse<T>	func Array_Reverse<T>(arr: *Array<T>)	Reverse elements in place
Array_Get<T>	func Array_Get<T>(arr: *Array<T>, index: uint) -> T	Get element at index
Array_Set<T>	func Array_Set<T>(arr: *Array<T>, index: uint, value: T)	Set element at index
Array_First<T>	func Array_First<T>(arr: *Array<T>) -> T	First element (bounds-checked)
Array_Last<T>	func Array_Last<T>(arr: *Array<T>) -> T	Last element (bounds-checked)
Array_Len<T>	func Array_Len<T>(arr: *Array<T>) -> uint	Get length
Array_Cap<T>	func Array_Cap<T>(arr: *Array<T>) -> uint	Get capacity
Array_IsEmpty<T>	func Array_IsEmpty<T>(arr: *Array<T>) -> bool	True if length is 0
Array_Clear<T>	func Array_Clear<T>(arr: *Array<T>)	Set length to 0 (keeps capacity)
Array_Reserve<T>	func Array_Reserve<T>(arr: *Array<T>, minCap: uint)	Grow capacity if needed
Array_Free<T>	func Array_Free<T>(arr: *Array<T>)	Free memory
Array_Drop<T>	func Array_Drop<T>(self: *Array<T>)	Drop trait entry (same as Array_Free)

RAII: Array<T> is auto-dropped at scope exit. Prefer letting the compiler call Array_Drop over manual Array_Free when ownership is clear. If you move an array into a struct field, the source local is not dropped (see LanguageRef Drop and RAII / examples/move_field.bux).

Example

import Std::Array::{Array, Array_New, Array_Push, Array_Get};

func Main() -> int {
    let arr: Array<int> = Array_New<int>(4);
    Array_Push<int>(&arr, 10);
    Array_Push<int>(&arr, 20);
    PrintInt(Array_Get<int>(&arr, 0));  // 10
    // Array_Drop runs at end of Main (or call Array_Free manually)
    return 0;
}

---

Std::Drop

Trait for automatic cleanup (RAII). Defined in lib/Drop.bux:

interface Drop {
    func Drop(self: *Self);
}

Implement with extend Type for Drop { func Drop(self: *Type) { … } } or mark the type @[Drop] and provide Type_Drop. Full rules (early return, field-move skip Drop, move-on-return): LanguageRef → Drop and RAII.

Examples: examples/drop_early_return.bux, examples/move_field.bux.

---

Std::Iter

Lightweight iterator over Array<T> (index-based, no allocation).

Types

struct Iter<T> {
    data: *T,
    len: uint,
    pos: uint,
}

Functions

Function	Signature	Description
Array_Iter<T>	func Array_Iter<T>(arr: *Array<T>) -> Iter<T>	Create iterator from array
Iter_HasNext<T>	func Iter_HasNext<T>(it: *Iter<T>) -> bool	Check if more elements remain
Iter_Next<T>	func Iter_Next<T>(it: *Iter<T>) -> T	Get next element and advance
Iter_Peek<T>	func Iter_Peek<T>(it: *Iter<T>) -> T	Peek current element without advancing
Iter_Reset<T>	func Iter_Reset<T>(it: *Iter<T>)	Reset to start
Iter_Pos<T>	func Iter_Pos<T>(it: *Iter<T>) -> uint	Current position
Iter_Len<T>	func Iter_Len<T>(it: *Iter<T>) -> uint	Total length
Iter_Count<T>	func Iter_Count<T>(it: *Iter<T>) -> uint	Count remaining elements
Iter_Skip<T>	func Iter_Skip<T>(it: *Iter<T>, n: uint)	Skip N elements
Iter_Take<T>	func Iter_Take<T>(it: *Iter<T>, n: uint) -> Iter<T>	Take first N elements as new iterator
Iter_AnyEq<T>	func Iter_AnyEq<T>(it: *Iter<T>, value: T) -> bool	True if any remaining element equals value
Iter_AllEq<T>	func Iter_AllEq<T>(it: *Iter<T>, value: T) -> bool	True if all remaining equal value
Iter_Collect<T>	func Iter_Collect<T>(it: *Iter<T>) -> Array<T>	Collect remaining into a new Array

Higher-order (generic + int aliases)

Take fat function pointers / closures. Prefer the generic forms; *Int aliases remain for compatibility.

Function	Signature	Description
Iter_Map<T,U>	func Iter_Map<T,U>(it: *Iter<T>, f: func(T) -> U) -> Array<U>	Map T → U
Iter_Filter<T>	func Iter_Filter<T>(it: *Iter<T>, pred: func(T) -> bool) -> Array<T>	Keep matching
Iter_Fold<T,Acc>	func Iter_Fold<T,Acc>(it: *Iter<T>, init: Acc, f: func(Acc, T) -> Acc) -> Acc	Left fold
Iter_ForEach<T>	func Iter_ForEach<T>(it: *Iter<T>, f: func(T) -> int)	Side-effect per element
Iter_Any<T>	func Iter_Any<T>(it: *Iter<T>, pred: func(T) -> bool) -> bool	Any matches pred
Iter_All<T>	func Iter_All<T>(it: *Iter<T>, pred: func(T) -> bool) -> bool	All match pred
Iter_MapInt …	wrappers → Iter_Map<int,int> etc.	Back-compat
Iter_SumInt	func Iter_SumInt(it: *Iter<int>) -> int	Sum remaining ints

Example

import Std::Array::*;
import Std::Iter::*;
import Std::Io::{PrintInt, PrintLine};

func Main() -> int {
    let arr: Array<int> = Array_New<int>(4);
    Array_Push<int>(&arr, 10);
    Array_Push<int>(&arr, 20);
    Array_Push<int>(&arr, 30);

    let it: Iter<int> = Array_Iter<int>(&arr);
    while Iter_HasNext<int>(&it) {
        PrintInt(Iter_Next<int>(&it));
        PrintLine("");
    }

    Array_Free<int>(&arr);
    return 0;
}

---

Std::String

String manipulation utilities.

Core Functions

Function	Signature	Description
String_Len	func String_Len(s: String) -> uint	Length of string
String_Eq	func String_Eq(a: String, b: String) -> bool	Compare strings
String_Concat	func String_Concat(a: String, b: String) -> String	Concatenate (allocates)
String_Copy	func String_Copy(s: String) -> String	Copy string (allocates)
String_StartsWith	func String_StartsWith(s: String, prefix: String) -> bool	Check prefix
String_EndsWith	func String_EndsWith(s: String, suffix: String) -> bool	Check suffix
String_Contains	func String_Contains(s: String, substr: String) -> bool	Check substring

Slicing & Trimming

Function	Signature	Description
String_Slice	func String_Slice(s: String, start: uint, len: uint) -> String	Extract substring
String_Trim	func String_Trim(s: String) -> String	Trim both sides
String_TrimLeft	func String_TrimLeft(s: String) -> String	Trim left side
String_TrimRight	func String_TrimRight(s: String) -> String	Trim right side

Split & Join

Function	Signature	Description
String_SplitCount	func String_SplitCount(s: String, delim: String) -> uint	Count parts
String_SplitPart	func String_SplitPart(s: String, delim: String, index: uint) -> String	Get nth part (0-indexed)
String_Join2	func String_Join2(a: String, b: String, sep: String) -> String	Join two strings with separator

Conversion

Function	Signature	Description
String_FromInt	func String_FromInt(n: int64) -> String	Int to string
String_FromFloat	func String_FromFloat(f: float64) -> String	Float to string
String_ToInt	func String_ToInt(s: String) -> int64	String to int
String_ToFloat	func String_ToFloat(s: String) -> float64	String to float

Find, Replace & Format

Function	Signature	Description
String_IsEmpty	func String_IsEmpty(s: String) -> bool	True if length is 0
String_IsBlank	func String_IsBlank(s: String) -> bool	True if empty or only whitespace
String_Repeat	func String_Repeat(s: String, count: uint) -> String	Repeat string N times
String_Find	func String_Find(haystack: String, needle: String) -> String	Find substring (returns pointer; 0 = not found)
String_IndexOf	func String_IndexOf(s: String, needle: String) -> int	Byte index of first match, or -1
String_Cmp	func String_Cmp(a: String, b: String) -> int	Lexicographic compare (strcmp)
String_ToUpper	func String_ToUpper(s: String) -> String	ASCII a–z → upper (allocates)
String_ToLower	func String_ToLower(s: String) -> String	ASCII A–Z → lower (allocates)
String_Replace	func String_Replace(s: String, old: String, new: String) -> String	Replace first occurrence
String_ReplaceAll	func String_ReplaceAll(s: String, old: String, new: String) -> String	Replace all non-overlapping occurrences
String_Format1	func String_Format1(pattern: String, a0: String) -> String	Format with 1 arg ({0})
String_Format2	func String_Format2(pattern: String, a0: String, a1: String) -> String	Format with 2 args
String_Format3	func String_Format3(pattern: String, a0: String, a1: String, a2: String) -> String	Format with 3 args

Example

import Std::String;

func Main() -> int {
    let s: String = String_Replace("hello world", "world", "Bux");
    PrintLine(s);  // "hello Bux"

    let fmt: String = String_Format2("{0} + {1} = magic", "Bux", "QBE");
    PrintLine(fmt);  // "Bux + QBE = magic"

    let found: String = String_Find("hello world", "world");
    if found as uint != 0 {
        PrintLine("found!");
    }
    return 0;
}

---

Std::StringBuilder

Efficient string construction using a dynamic buffer.

Types

struct StringBuilder {
    handle: *void,
}

Functions

Function	Signature	Description
StringBuilder_New	func StringBuilder_New() -> StringBuilder	Create with default capacity (64)
StringBuilder_NewCap	func StringBuilder_NewCap(cap: uint) -> StringBuilder	Create with custom capacity
StringBuilder_Append	func StringBuilder_Append(sb: *StringBuilder, s: String)	Append string
StringBuilder_AppendInt	func StringBuilder_AppendInt(sb: *StringBuilder, n: int64)	Append integer
StringBuilder_AppendFloat	func StringBuilder_AppendFloat(sb: *StringBuilder, f: float64)	Append float
StringBuilder_AppendChar	func StringBuilder_AppendChar(sb: *StringBuilder, c: char8)	Append char
StringBuilder_Build	func StringBuilder_Build(sb: *StringBuilder) -> String	Build result string
StringBuilder_Free	func StringBuilder_Free(sb: *StringBuilder)	Free memory

Example

import Std::String::{StringBuilder, StringBuilder_New, StringBuilder_Append, StringBuilder_AppendInt, StringBuilder_Build, StringBuilder_Free};

func Main() -> int {
    let sb: StringBuilder = StringBuilder_New();
    StringBuilder_Append(&sb, "Hello, ");
    StringBuilder_Append(&sb, "World! #");
    StringBuilder_AppendInt(&sb, 42);
    PrintLine(StringBuilder_Build(&sb));  // "Hello, World! #42"
    StringBuilder_Free(&sb);
    return 0;
}

---

Std::Mem

Memory management wrappers around C runtime functions.

Function	Signature	Description
Alloc	func Alloc(size: uint) -> *void	Allocate memory
Realloc	func Realloc(ptr: *void, size: uint) -> *void	Reallocate memory
Free	func Free(ptr: *void)	Free memory
MemEq	func MemEq(a: *void, b: *void, size: uint) -> bool	Byte-wise memory comparison
New	func New<T>() -> *T	Typed allocation (sizeof(T) bytes)

Example

import Std::Mem;

func Main() -> int {
    let p: *void = Alloc(64);
    Free(p);

    let n: *int = New<int>();
    // use n...
    Free(n as *void);
    return 0;
}

---

Std::Set

Generic hash set for deduplication and membership testing.

Types

struct SetEntry<T> {
    value: T,
    occupied: bool,
}

struct Set<T> {
    entries: *SetEntry<T>,
    cap: uint,
    len: uint,
}

Functions

Function	Signature	Description
Set_New<T>	func Set_New<T>(cap: uint) -> Set<T>	Create set
Set_Add<T>	func Set_Add<T>(s: *Set<T>, value: T)	Insert element (ignores duplicates)
Set_Has<T>	func Set_Has<T>(s: *Set<T>, value: T) -> bool	Check membership
Set_Remove<T>	func Set_Remove<T>(s: *Set<T>, value: T) -> bool	Remove value
Set_Clear<T>	func Set_Clear<T>(s: *Set<T>)	Clear all elements
Set_IsEmpty<T>	func Set_IsEmpty<T>(s: *Set<T>) -> bool	True if empty
Set_Len<T>	func Set_Len<T>(s: *Set<T>) -> uint	Element count
Set_Free<T>	func Set_Free<T>(s: *Set<T>)	Free memory

Example

import Std::Set;

func Main() -> int {
    var s: Set<int> = Set_New<int>(16);
    Set_Add(&s, 10);
    Set_Add(&s, 20);
    Set_Add(&s, 10);  // duplicate, ignored
    if Set_Has(&s, 10) {
        PrintLine("has 10");
    }
    Set_Free(&s);
    return 0;
}

---

Std::Map

Generic hash map Map<K, V> for value-type keys (int, float, etc.).

Types

struct MapEntry<K, V> {
    key: K,
    value: V,
    occupied: bool,
}

struct Map<K, V> {
    entries: *MapEntry<K, V>,
    cap: uint,
    len: uint,
}

Functions

Function	Signature	Description
Map_New<K,V>	func Map_New<K,V>(cap: uint) -> Map<K,V>	Create map
Map_Set<K,V>	func Map_Set<K,V>(m: *Map<K,V>, key: K, value: V)	Insert/update
Map_Get<K,V>	func Map_Get<K,V>(m: *Map<K,V>, key: K) -> V	Get value (zero if missing)
Map_GetOr<K,V>	func Map_GetOr<K,V>(m: *Map<K,V>, key: K, defaultVal: V) -> V	Get or default if missing
Map_Has<K,V>	func Map_Has<K,V>(m: *Map<K,V>, key: K) -> bool	Check key exists
Map_Remove<K,V>	func Map_Remove<K,V>(m: *Map<K,V>, key: K) -> bool	Remove key (true if present)
Map_Clear<K,V>	func Map_Clear<K,V>(m: *Map<K,V>)	Remove all entries (keeps capacity)
Map_IsEmpty<K,V>	func Map_IsEmpty<K,V>(m: *Map<K,V>) -> bool	True if no entries
Map_Len<K,V>	func Map_Len<K,V>(m: *Map<K,V>) -> uint	Entry count
Map_Free<K,V>	func Map_Free<K,V>(m: *Map<K,V>)	Free memory

Example

import Std::Map::{Map, Map_New, Map_Set, Map_Get, Map_Free};

func Main() -> int {
    let m: Map<int, String> = Map_New<int, String>(16);
    Map_Set<int, String>(&m, 1, "one");
    Map_Set<int, String>(&m, 2, "two");
    PrintLine(Map_Get<int, String>(&m, 1));  // "one"
    Map_Free<int, String>(&m);
    return 0;
}

Note: For String keys, use StringMap<V> below which uses strcmp for key comparison.

---

Std::StringMap

Specialized hash map for String keys with any value type.

Types

struct StringMapEntry<V> {
    key: String,
    value: V,
    occupied: bool,
}

struct StringMap<V> {
    entries: *StringMapEntry<V>,
    cap: uint,
    len: uint,
}

Functions

Function	Signature	Description
StringMap_New<V>	func StringMap_New<V>(cap: uint) -> StringMap<V>	Create map
StringMap_Set<V>	func StringMap_Set<V>(m: *StringMap<V>, key: String, value: V)	Insert/update
StringMap_Get<V>	func StringMap_Get<V>(m: *StringMap<V>, key: String) -> V	Get value
StringMap_GetOr<V>	func StringMap_GetOr<V>(m: *StringMap<V>, key: String, defaultVal: V) -> V	Get or default if missing
StringMap_Has<V>	func StringMap_Has<V>(m: *StringMap<V>, key: String) -> bool	Check key exists
StringMap_Remove<V>	func StringMap_Remove<V>(m: *StringMap<V>, key: String) -> bool	Remove key
StringMap_Clear<V>	func StringMap_Clear<V>(m: *StringMap<V>)	Clear all entries
StringMap_IsEmpty<V>	func StringMap_IsEmpty<V>(m: *StringMap<V>) -> bool	True if empty
StringMap_Len<V>	func StringMap_Len<V>(m: *StringMap<V>) -> uint	Entry count
StringMap_Free<V>	func StringMap_Free<V>(m: *StringMap<V>)	Free memory

---

Std::Path

Path manipulation utilities.

Function	Signature	Description
Path_Join	func Path_Join(a: String, b: String) -> String	Join path segments
Path_Parent	func Path_Parent(path: String) -> String	Get parent directory
Path_Ext	func Path_Ext(path: String) -> String	Get file extension

Example

import Std::Path::{Path_Join, Path_Parent, Path_Ext};

func Main() -> int {
    PrintLine(Path_Join("/home", "docs"));       // "/home/docs"
    PrintLine(Path_Parent("/a/b/c.txt"));         // "/a/b"
    PrintLine(Path_Ext("main.bux"));              // ".bux"
    return 0;
}

---

Runtime Functions

These C functions are provided by runtime.c and are available via extern declarations.

Function	Signature	Description
bux_alloc	func bux_alloc(size: uint) -> *void	Allocate memory
bux_realloc	func bux_realloc(ptr: *void, size: uint) -> *void	Reallocate memory
bux_free	func bux_free(ptr: *void)	Free memory
bux_bounds_check	func bux_bounds_check(index: uint, len: uint)	Panic on OOB
bux_hash_string	func bux_hash_string(s: String) -> uint	DJB2 hash for strings
bux_hash_bytes	func bux_hash_bytes(ptr: *void, size: uint) -> uint	DJB2 hash for raw bytes

---

Std::Task

Pthread-based threading primitives.

Types

struct TaskHandle {
    handle: *void;
}

Functions

Function	Signature	Description
Task_Spawn	func Task_Spawn(fn: *void, arg: *void) -> TaskHandle	Spawn a new thread running fn(arg)
Task_Join	func Task_Join(t: TaskHandle)	Block until thread completes
Task_Sleep	func Task_Sleep(ms: int64)	Sleep current thread for N milliseconds

Example

import Std::Task::{Task_Spawn, Task_Join, TaskHandle};

func Worker(arg: *void) -> *void {
    PrintLine("Hello from thread!");
    return null;
}

func Main() -> int {
    let handle: TaskHandle = Task_Spawn(Worker as *void, null);
    Task_Join(handle);
    PrintLine("Thread finished");
    return 0;
}

---

Std::Sync

Synchronization primitives: Mutex and RwLock.

Types

struct Mutex {
    handle: *void;
}

struct RwLock {
    handle: *void;
}

Functions

Function	Signature	Description
Mutex_New	func Mutex_New() -> Mutex	Create a new mutex
Mutex_Lock	func Mutex_Lock(m: *Mutex)	Acquire lock (blocks)
Mutex_Unlock	func Mutex_Unlock(m: *Mutex)	Release lock
Mutex_Free	func Mutex_Free(m: *Mutex)	Destroy mutex
RwLock_New	func RwLock_New() -> RwLock	Create a new read-write lock
RwLock_ReadLock	func RwLock_ReadLock(rw: *RwLock)	Acquire read lock (shared)
RwLock_WriteLock	func RwLock_WriteLock(rw: *RwLock)	Acquire write lock (exclusive)
RwLock_Unlock	func RwLock_Unlock(rw: *RwLock)	Release read or write lock
RwLock_Free	func RwLock_Free(rw: *RwLock)	Destroy rwlock

Example

import Std::Io::{PrintLine, PrintInt};
import Std::Task::{Task_Join, TaskHandle};
import Std::Sync::{Mutex, Mutex_New, Mutex_Lock, Mutex_Unlock};

struct Counter {
    value: int;
    mtx: Mutex;
}

func Incrementer(arg: *void) -> *void {
    let c: *Counter = arg as *Counter;
    var i: int = 0;
    while i < 100000 {
        Mutex_Lock(&c.mtx);
        c.value = c.value + 1;
        Mutex_Unlock(&c.mtx);
        i = i + 1;
    }
    return null;
}

func Main() -> int {
    var counter: Counter = Counter { value: 0, mtx: Mutex_New() };
    let a: *void = spawn Incrementer(&counter);
    let b: *void = spawn Incrementer(&counter);
    Task_Join(TaskHandle { handle: a });
    Task_Join(TaskHandle { handle: b });
    PrintLine("Counter:");
    PrintInt(counter.value);
    return 0;
}

---

Std::Channel

Generic channel for thread communication over pthread mutex/cond.

Types

struct Channel<T> {
    handle: *void;
}

Functions

Function	Signature	Description
Channel_New<T>	func Channel_New<T>(capacity: int64) -> Channel<T>	Create buffered channel
Channel_Send<T>	func Channel_Send<T>(ch: *Channel<T>, value: T)	Send value (blocks if full)
Channel_Recv<T>	func Channel_Recv<T>(ch: *Channel<T>) -> T	Receive value (blocks if empty)
Channel_Close<T>	func Channel_Close<T>(ch: *Channel<T>)	Close channel
Channel_Free<T>	func Channel_Free<T>(ch: *Channel<T>)	Free channel memory

Non-generic wrappers

Function	Signature	Description
Channel_SendInt	func Channel_SendInt(ch: *Channel<int>, value: int)	Send int (no monomorphization issues)
Channel_RecvInt	func Channel_RecvInt(ch: *Channel<int>) -> int	Recv int (returns 0 if closed+empty)
Channel_SendFloat64	func Channel_SendFloat64(ch: *Channel<float64>, value: float64)	Send float64
Channel_RecvFloat64	func Channel_RecvFloat64(ch: *Channel<float64>) -> float64	Recv float64

Example

import Std::Io::{PrintLine, PrintInt};
import Std::Task::{Task_Join, TaskHandle};
import Std::Channel::{Channel, Channel_New, Channel_SendInt, Channel_RecvInt, Channel_Close};

func Producer(chPtr: *Channel<int>) {
    var i: int = 1;
    while i <= 5 {
        Channel_SendInt(chPtr, i * 10);
        i = i + 1;
    }
    Channel_Close<int>(chPtr);
}

func Consumer(chPtr: *Channel<int>) {
    var total: int = 0;
    while true {
        let val: int = Channel_RecvInt(chPtr);
        if val == 0 { break; }
        total = total + val;
    }
    PrintLine("Total:");
    PrintInt(total);
}

func Main() -> int {
    let ch: Channel<int> = Channel_New<int>(3);
    let p: *void = spawn Producer(&ch);
    let c: *void = spawn Consumer(&ch);
    Task_Join(TaskHandle { handle: p });
    Task_Join(TaskHandle { handle: c });
    return 0;
}

---

Std::Net

TCP socket operations.

Functions

Function	Signature	Description
Net_Create	func Net_Create() -> int	Create TCP socket (-1 on error)
Net_SetReuse	func Net_SetReuse(fd: int) -> bool	Enable SO_REUSEADDR
Net_Bind	func Net_Bind(fd: int, addr: String, port: int) -> bool	Bind socket
Net_Listen	func Net_Listen(fd: int, backlog: int) -> bool	Start listening
Net_Accept	func Net_Accept(fd: int) -> int	Accept connection (-1 on error)
Net_Connect	func Net_Connect(fd: int, addr: String, port: int) -> bool	Connect to remote
Net_Send	func Net_Send(fd: int, data: String) -> int	Send data (bytes sent or -1)
Net_Recv	func Net_Recv(fd: int, maxLen: int) -> String	Receive up to maxLen bytes
Net_Close	func Net_Close(fd: int) -> bool	Close socket
Net_LastError	func Net_LastError() -> String	Get last socket error

Example — Echo Server

import Std::Net::*;
import Std::Io::PrintLine;

func Main() -> int {
    let fd: int = Net_Create();
    Net_SetReuse(fd);
    Net_Bind(fd, "127.0.0.1", 8080);
    Net_Listen(fd, 10);
    PrintLine("Listening on :8080");
    let client: int = Net_Accept(fd);
    let msg: String = Net_Recv(client, 1024);
    Net_Send(client, msg);
    Net_Close(client);
    Net_Close(fd);
    return 0;
}

---

Std::Json

JSON parser and serializer using a flat struct with int tag.

Types

struct JsonValue {
    tag: int,
    boolVal: bool,
    numVal: float64,
    strVal: String,
    arrData: *JsonValue,
    arrLen: uint,
    objKeys: *String,
    objValues: *JsonValue,
    objLen: uint
}

Constructors

Function	Signature	Description
Json_Null	func Json_Null() -> JsonValue	Null value
Json_Bool	func Json_Bool(b: bool) -> JsonValue	Boolean value
Json_Number	func Json_Number(n: float64) -> JsonValue	Number value
Json_String	func Json_String(s: String) -> JsonValue	String value
Json_Array	func Json_Array() -> JsonValue	Empty array
Json_Object	func Json_Object() -> JsonValue	Empty object

Accessors

Function	Signature	Description
Json_IsNull	func Json_IsNull(v: JsonValue) -> bool	Check if null
Json_AsBool	func Json_AsBool(v: JsonValue) -> bool	Get bool (false if wrong type)
Json_AsNumber	func Json_AsNumber(v: JsonValue) -> float64	Get number (0.0 if wrong type)
Json_AsString	func Json_AsString(v: JsonValue) -> String	Get string ("" if wrong type)
Json_ArrayLen	func Json_ArrayLen(v: JsonValue) -> uint	Array length
Json_ArrayGet	func Json_ArrayGet(v: JsonValue, index: uint) -> JsonValue	Get array element
Json_ObjectLen	func Json_ObjectLen(v: JsonValue) -> uint	Object key count
Json_ObjectGet	func Json_ObjectGet(v: JsonValue, key: String) -> JsonValue	Get object value by key
Json_ObjectHas	func Json_ObjectHas(v: JsonValue, key: String) -> bool	Check if key exists

Mutators

Function	Signature	Description
Json_ArrayPush	func Json_ArrayPush(self: *JsonValue, val: JsonValue)	Append to array
Json_ObjectSet	func Json_ObjectSet(self: *JsonValue, key: String, val: JsonValue)	Set object key

Parser / Serializer

Function	Signature	Description
Json_Parse	func Json_Parse(s: String) -> JsonValue	Parse JSON string
Json_Stringify	func Json_Stringify(v: JsonValue) -> String	Serialize to JSON string

Example

import Std::Json::*;
import Std::Io::PrintLine;

func Main() -> int {
    let json: JsonValue = Json_Parse(`{"name": "Bux", "version": 1}`);
    let name: String = Json_AsString(Json_ObjectGet(json, "name"));
    PrintLine(name);  // "Bux"

    var arr: JsonValue = Json_Array();
    Json_ArrayPush(&arr, Json_Number(10));
    Json_ArrayPush(&arr, Json_Number(20));
    PrintLine(Json_Stringify(arr));  // [10,20]
    return 0;
}

---

Std::Crypto

Cryptographic primitives via OpenSSL (-lcrypto).

Functions

Function	Signature	Description
Crypto_Sha256	func Crypto_Sha256(data: String) -> String	SHA-256 hex string
Crypto_HmacSha256	func Crypto_HmacSha256(key: String, message: String) -> String	HMAC-SHA256 hex string
Crypto_HmacSha256Raw	func Crypto_HmacSha256Raw(key: String, message: String) -> String	HMAC-SHA256 base64 string
Crypto_RandomBytes	func Crypto_RandomBytes(n: int) -> String	n random bytes as base64
Crypto_Base64Encode	func Crypto_Base64Encode(s: String) -> String	Base64 encode
Crypto_Base64Decode	func Crypto_Base64Decode(s: String) -> String	Base64 decode

Example

import Std::Crypto::*;
import Std::Io::PrintLine;

func Main() -> int {
    let hash: String = Crypto_Sha256("hello");
    PrintLine(hash);

    let hmac: String = Crypto_HmacSha256("key", "message");
    PrintLine(hmac);

    let rand: String = Crypto_RandomBytes(16);
    PrintLine(rand);
    return 0;
}

---

Std::Fmt

Convenience wrappers for string formatting.

Functions

Function	Signature	Description
Fmt_Fmt1	func Fmt_Fmt1(pattern: String, a: String) -> String	Format with 1 arg
Fmt_Fmt2	func Fmt_Fmt2(pattern: String, a: String, b: String) -> String	Format with 2 args
Fmt_Fmt3	func Fmt_Fmt3(pattern: String, a: String, b: String, c: String) -> String	Format with 3 args
Fmt_FmtInt	func Fmt_FmtInt(pattern: String, n: int64) -> String	Format with int arg
Fmt_FmtInt2	func Fmt_FmtInt2(pattern: String, n1: int64, n2: int64) -> String	Format with 2 int args
Fmt_FmtFloat	func Fmt_FmtFloat(pattern: String, f: float64) -> String	Format with float arg
Fmt_FmtBool	func Fmt_FmtBool(pattern: String, b: bool) -> String	Format with bool arg

Example

import Std::Fmt::*;
import Std::Io::PrintLine;

func Main() -> int {
    PrintLine(Fmt_Fmt1("Hello, {0}!", "World"));
    PrintLine(Fmt_FmtInt("Count: {0}", 42));
    PrintLine(Fmt_FmtFloat("Pi: {0}", 3.14159));
    return 0;
}

---

Std::Math

Mathematical functions.

Functions

Function	Signature	Description
Sqrt	func Sqrt(x: float64) -> float64	Square root
Pow	func Pow(x: float64, y: float64) -> float64	Power
Abs	func Abs(n: int64) -> int64	Absolute value (int)
AbsF	func AbsF(f: float64) -> float64	Absolute value (float)
Min	func Min(a: int64, b: int64) -> int64	Minimum (int)
Max	func Max(a: int64, b: int64) -> int64	Maximum (int)
MinF	func MinF(a: float64, b: float64) -> float64	Minimum (float)
MaxF	func MaxF(a: float64, b: float64) -> float64	Maximum (float)

Example

import Std::Math::*;
import Std::Io::PrintInt;

func Main() -> int {
    PrintInt(Max(10, 20) as int);   // 20
    PrintInt(Min(10, 20) as int);   // 10
    return 0;
}

---

Std::Async

Low-level async runtime for stackful coroutines. These functions are used by the async/await language features.

Functions

Function	Signature	Description
bux_async_spawn	func bux_async_spawn(fn: *void) -> *void	Create a new coroutine from a function pointer
bux_async_yield	func bux_async_yield()	Yield control to the scheduler
bux_async_await	func bux_async_await(handle: *void) -> *void	Block until coroutine completes, return result pointer
bux_async_run	func bux_async_run()	Run the round-robin scheduler
bux_async_sleep	func bux_async_sleep(ms: int64)	Non-blocking sleep for ms milliseconds
bux_async_return	func bux_async_return(value: *void, size: int64)	Copy return value into task result buffer
bux_now_ms	func bux_now_ms() -> int64	Monotonic clock in milliseconds

Example

extern func bux_async_yield();
extern func bux_async_spawn(fn: *void) -> *void;
extern func bux_async_await(handle: *void) -> *void;

async func Compute() -> int {
    bux_async_yield();
    return 42;
}

func Main() -> int {
    let h = spawn Compute();
    let r: int = h.await as int;
    return 0;
}

---

Future Modules

• Std::Result — Shipped via algebraic enums ✅
• Std::Option — Shipped via algebraic enums ✅
• Std::Math — Sqrt, Pow, Min, Max, Abs ✅
• Std::Fs — Directory operations ✅
• Std::Mem — Memory wrappers ✅
• Std::Set — Hash set ✅
• Std::Path — Path manipulation ✅
• Std::Os — Args, Env, Cwd, Chdir ✅
• Std::Time — NowMs, NowUs, SleepMs ✅
• Std::Process — Run, Output ✅
• Std::Fmt — String formatting with interpolation ✅
• Std::Iter — Iterator over Array<T> ✅
• Std::Task / Std::Channel — Lightweight concurrency (pthread-based threads) ✅
• Std::Net — TCP sockets ✅
• Std::Json — JSON parser/serializer ✅
• Std::Crypto — SHA-256, HMAC, Base64, random bytes ✅
• Std::Math — Sqrt, Pow, Abs, Min, Max ✅

---

Std::Os

Operating system interface.

import Std::Os::{Os_ArgsCount, Os_Args, Os_GetEnv, Os_SetEnv, Os_GetCwd, Os_Chdir, Os_Exit};

Function	Signature	Description
Os_ArgsCount	func Os_ArgsCount() -> int	Number of command-line arguments
Os_Args	func Os_Args(index: int) -> String	Get argument at index
Os_GetEnv	func Os_GetEnv(name: String) -> String	Get environment variable
Os_SetEnv	func Os_SetEnv(name: String, value: String) -> bool	Set environment variable
Os_GetCwd	func Os_GetCwd() -> String	Get current working directory
Os_Chdir	func Os_Chdir(path: String) -> bool	Change directory
Os_Exit	func Os_Exit(code: int)	Terminate process with exit code

---

Std::Test

Lightweight assertions for bux test and example programs.

import Std::Test::*;

Function	Signature	Description
Test_Assert	func Test_Assert(cond: bool)	Panic if false
Test_AssertTrue / Test_AssertFalse	func ...(cond: bool)	Boolean asserts
Test_AssertEqInt	func Test_AssertEqInt(a: int, b: int)	Integer equality
Test_AssertNeqInt	func Test_AssertNeqInt(a: int, b: int)	Integer inequality
Test_AssertEqString	func Test_AssertEqString(a: String, b: String)	String equality
Test_AssertNeqString	func Test_AssertNeqString(a: String, b: String)	String inequality
Test_AssertEqBool	func Test_AssertEqBool(a: bool, b: bool)	Boolean equality
Test_Fail / Test_Pass	func ...(msg: String)	Explicit fail / log pass
Test_Exit	func Test_Exit(code: int)	Exit with code

---

Std::Time

Time utilities.

import Std::Time::{Time_NowMs, Time_NowUs, Time_SleepMs};

Function	Signature	Description
Time_NowMs	func Time_NowMs() -> int64	Current time in milliseconds
Time_NowUs	func Time_NowUs() -> int64	Current time in microseconds
Time_SleepMs	func Time_SleepMs(ms: int64)	Sleep for N milliseconds

---

Std::Process

Process spawning.

import Std::Process::{Process_Run, Process_Output};

Function	Signature	Description
Process_Run	func Process_Run(cmd: String) -> int	Run command, return exit code
Process_Output	func Process_Output(cmd: String) -> String	Run command, capture stdout