Skip to content

Sushi Standard Library

Complete reference for Sushi's standard library modules and types.

Table of Contents

Core Types

  • Result - Error handling for fallible operations
  • Maybe - Optional values

Collections

  • List - Dynamic growable array
  • HashMap - Hash table with open addressing
  • Arrays - Fixed and dynamic array methods
  • Strings - 33 string manipulation methods
  • Iter combinators - map/filter/fold/compose over List<T>

I/O Operations

  • Console I/O - println, print, stdin/stdout/stderr
  • File I/O - File operations with error handling

System Modules

  • Math - Mathematical operations (abs, min, max, sqrt, pow, trig)
  • Random - Pseudo-random number generation (rand, rand_range, rand_f64, srand)
  • Time - High-precision sleep functions
  • Environment - Environment variables and system information
  • Process Control - Process management (getcwd, chdir, exit, getpid, getuid)
  • Platform - Platform detection and OS-specific utilities

Quick Reference

Importing Modules

use <collections/strings>  # String methods
use <collections/iter>     # Higher-order combinators (map/filter/fold/compose)
use <io/stdio>             # Console I/O
use <io/files>             # File operations
use <math>                 # Math functions
use <random>               # Random number generation
use <time>                 # Sleep functions
use <sys/env>              # Environment variables
use <sys/process>          # Process control

Common Patterns

Error Handling

# Using ?? operator for propagation
fn read_config() string:
    let file f = open("config.txt", FileMode.Read())??
    let string content = f.read()
    f.close()
    return Result.Ok(content)

# Using pattern matching
match parse_number("42"):
    Result.Ok(n) -> println("Got: {n}")
    Result.Err() -> println("Parse failed")

# Using .realise() for defaults
let i32 port = config.get("port").realise(8080)

Optional Values

# Safe array access
match arr.get(0):
    Maybe.Some(first) -> println("First: {first}")
    Maybe.None() -> println("Array empty")

# String searching
let string text = "hello world"
let Maybe<i32> pos = text.find("world")

Collections

use <collections/hashmap>

# List<T> - no import required
let List<i32> numbers = List.new()
numbers.push(1)
numbers.push(2)
numbers.push(3)

# HashMap<K, V> - requires import
let HashMap<string, i32> ages = HashMap.new()
ages.insert("Alice", 30)
match ages.get("Alice"):
    Maybe.Some(age) -> println("Age: {age}")
    Maybe.None() -> println("Not found")

# Arrays - built-in
let i32[] arr = from([1, 2, 3])
arr.push(4)
foreach(n in arr.iter()):
    println(n)

String Processing

use <collections/strings>

let string text = "  Hello World  "
let string clean = text.trim().lower()  # "hello world"

let string[] parts = "a,b,c".split(',')
let string joined = ','.join(parts)  # "a,b,c"

let string path = "/home/user/file.txt"
let string filename = path.strip_prefix("/home/user/")  # "file.txt"

File I/O

use <io/files>

# Reading files
match open("data.txt", FileMode.Read()):
    FileResult.Ok(f) ->
        let string content = f.read()
        f.close()
        println(content)
    FileResult.Err(FileError.NotFound()) ->
        println("File not found")
    FileResult.Err(_) ->
        println("Other error")

# Writing files
match open("output.txt", FileMode.Write()):
    FileResult.Ok(f) ->
        f.write("Hello, file!")
        f.close()
    FileResult.Err(_) ->
        println("Failed to write")

Module Overview

Collections

List - Generic dynamic array (built-in, no import required): - Construction: new(), with_capacity() - Access: get(), len(), is_empty() - Modification: push(), pop(), insert(), remove(), clear() - Iteration: iter() for foreach loops - Memory: free(), destroy()

HashMap - Generic hash table (use <collections/hashmap>): - Construction: new() - Operations: insert(), get(), remove(), contains_key() - Iteration: keys(), values() - Automatic resizing at 0.75 load factor - Memory: free(), destroy()

Arrays - Built-in array support: - Fixed arrays: i32[10] - Dynamic arrays: i32[] with from([...]) - Methods: len(), get(), push(), pop(), iter(), clone() - Safe access with get() returns Maybe<T> - Unsafe direct indexing: arr[i]

Strings - 33 methods (use <collections/strings>): - Inspection, slicing, transformation, padding, stripping - Splitting/joining, case conversion, parsing - UTF-8 aware where needed

Iter combinators - higher-order functions over List<T> (use <collections/iter>): - map(xs, f), filter(xs, pred), fold(xs, init, f), compose(g, f) - Ordinary generic free functions (the first Sushi-source stdlib module, no bitcode) - Copy/primitive element types; pass a typed-param lambda (|i32 x| ...) or a function reference

I/O (use <io/stdio>, use <io/files>)

Console I/O: - println(), print() - Output with/without newline - stdin.read_line() - Read user input - stdout, stderr - Direct stream access

File I/O: - open() - Open files with Read/Write/Append modes - File methods: read(), read_line(), write(), close() - Error handling with FileResult and FileError enums

Math (use <math>)

All functions use a single polymorphic name (no type-suffixed variants): - Absolute value / min / max: abs(), min(), max() (return the argument's type) - Floating-point (f64): sqrt(), pow(), floor(), ceil(), round(), trunc() - Trigonometry: sin(), cos(), tan(), asin(), acos(), atan(), atan2() - Hyperbolic: sinh(), cosh(), tanh() - Exponential / logarithm: exp(), exp2(), log(), log2(), log10() - Utility: hypot() - Constants: PI, E, TAU

Time (use <time>)

High-precision sleep functions: - sleep(i64) - Sleep for N seconds - msleep(i64) - Sleep for N milliseconds - usleep(i64) - Sleep for N microseconds - nanosleep(i64, i64) - Nanosecond precision

Environment (use <sys/env>)

Environment and system: - getenv() - Get environment variable - setenv() - Set environment variable - unsetenv() - Remove environment variable - Process control: exit(), getcwd(), chdir()

Design Principles

  1. Explicit error handling - All fallible operations return Result<T> or Maybe<T>
  2. Memory safety - RAII cleanup, no manual memory management
  3. Zero-cost abstractions - Generics compile to concrete types
  4. UTF-8 by default - Strings are UTF-8, methods are aware where needed
  5. Immutability - String methods return new strings, arrays use RAII
  6. Type safety - No null, no undefined behavior, exhaustive pattern matching

Performance Notes

  • List: Amortized O(1) push, O(n) insert/remove
  • HashMap: O(1) average insert/get/remove, O(n) worst case
  • String methods: All allocate new strings, O(n) for most operations
  • Arrays: Direct memory access, bounds checked at runtime
  • Generics: Monomorphized at compile-time (no runtime overhead)

See Also