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_Get<T>	func Array_Get<T>(arr: *Array<T>, index: uint) -> T	Get element at index
Array_Len<T>	func Array_Len<T>(arr: *Array<T>) -> uint	Get length
Array_Free<T>	func Array_Free<T>(arr: *Array<T>)	Free memory

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_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_ToInt	func String_ToInt(s: String) -> int64	String to int

Find, Replace & Format

Function	Signature	Description
String_Find	func String_Find(haystack: String, needle: String) -> String	Find substring (returns pointer; 0 = not found)
String_Replace	func String_Replace(s: String, old: String, new: String) -> String	Replace first occurrence
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_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_Has<K,V>	func Map_Has<K,V>(m: *Map<K,V>, key: K) -> bool	Check key exists
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_Has<V>	func StringMap_Has<V>(m: *StringMap<V>, key: String) -> bool	Check key exists
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::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, Exit, Cwd ⏳
• Std::Process — Spawn subprocess ⏳
• Std::Fmt — String formatting with interpolation ⏳
• Std::Iter — Iterator trait and combinators ⏳
• Std::Task / Std::Channel — Lightweight concurrency (pthread-based threads) ✅