#rok standard library reference

This is the formal specification of the rok standard libraries. Where the language specification defines syntax and semantic mechanisms, the standard library specification supplies the meaning of the types, traits and functions those mechanisms need in order to actually work. It defines in one place which traits operators resolve to, which interfaces collections have, and on which guarantees async and I/O operate.

The language specification is collected separately in refs-lang/; this document covers only the specification. The actual implementation of the libraries is outside the scope of the spec.

#The 3-tier model

The standard libraries are not a single flat plane but are divided into three layers. Almost all systems code is written on top of safe abstractions, but implementing those abstractions eventually requires handling raw memory and FFI somewhere. Moreover, features that are meaningful only with a host environment, such as files or networking, must not exist at all on targets without such an environment, such as embedded. To expose these differences directly in the dependency graph, the libraries follow a 3-tier structure under the virtual namespace rok::: rok::bare / rok::core / rok::std.

rok::bare   (base, depends only on runtime extern "C")
  ↓
rok::core   (foundation, safe, all targets - uses rok::bare internally)
  ↓
rok::std   (target-dep - uses rok::core + rok::bare)

rok::bare exposes only raw capabilities at the bottom, and rok::core provides a safe foundation on top of it, identically on every target. rok::std adds host-dependent features on top of rok::core, completing the surface an ordinary application expects. Everyday code needs only rok::core; it reaches for rok::std the moment OS resources are needed, and imports rok::bare explicitly only when it must cross an abstraction boundary directly. The detailed dependency rules are covered in 0.1 Tier model.

#Chapters

#0. Meta - 000-meta/

Library-wide policies and tables.

• 0.1. The 3-tier model
• 0.2. Import policy (implicit use rok::core::**;)
• 0.3. Intrinsic mechanism - the compiler ↔ standard library boundary
• 0.4. #[lang] slot mapping table
• 0.5. Notation

#1. Unsafe - 100-bare/

Low-level / dangerous area. Explicit import required.

• 1.1. Pointer family (Ptr/ConstPtr/ManyPtr/CPtr - Zig arity-encoded + Rust strict provenance)
• 1.2. Cast operations (ptr_cast/align_cast/const_cast/reinterpret)
• 1.3. MaybeUninit<T> + Pod + raw mem ops
• 1.4. Raw allocation
• 1.5. Volatile memory access
• 1.6. Pinned<T> - GC pin (Go 1.21 Pinner model)
• 1.7. FFI - extern "C" / CStr / CString
• 1.8. WASM Component Model (ffi.wit)
• 1.9. rok::bare::mlir - direct access to MLIR dialects
• 1.10. rok::bare::mlir::plugin - registering user-defined dialects

#2. Rok - 200-core/

Safe area. All targets. use rok::core::**; applied implicitly (no separate prelude module).

• 2.1. Numeric types (int, float, auto-promote)
• 2.2. Niche wrappers (NonZero, NonNan, Finite, Positive)
• 2.3. Arithmetic / bitwise traits (Add, Sub, ..., Shl, Shr)
• 2.4. Compound assignment traits (AddAssign, ...)
• 2.5. Comparison traits (PartialEq, Eq, Ord, PartialOrd, Hash)
• 2.6. Broadcast traits (DotAdd, DotMul, ...)
• 2.7. Iter traits (Iterator, IntoIterator)
• 2.8. Stream (async iterator)
• 2.9. Collections (List, Dict, Set, Tuple, Slice)
• 2.10. fmt (Display, Debug, Formatter)
• 2.11. Conversion (From, Into, TryFrom, saturating_into, ...)
• 2.12. Reflection (Reflect, Inspect)
• 2.13. Marker traits (Clone, Copy)
• 2.14. Error types (TypeError, ValueError, ...)
• 2.15. Strings (str single mutable, char, c_char)
• 2.16. Sync primitives (Atomic, Mutex, RwLock, Cell)
• 2.17. Channel
• 2.18. task:: API
• 2.19. par:: API
• 2.20. Future / await integration
• 2.21. crypto:: - hashes, MACs, AEADs, key exchange, signatures

#3. Std - 300-std/

Target-dependent area. Explicit import.

• 3.1. fs:: - file system (atomic ops, Dir capability, reflink)
• 3.2. net:: - TCP/UDP/Unix + TLS 1.3 (HTTP is external)
• 3.3. time:: - Instant / SystemTime / Duration / BootTime
• 3.4. thread:: - OS threads (1:1, separate from tasks)
• 3.5. io:: - Reader / Writer / stdin/out/err (sync only - no async traits)
• 3.6. env:: - environment variables / args / directories
• 3.7. process:: - Command / pidfd / kill_on_drop
• 3.8. path:: - UTF-8 Path + / operator (Python pathlib style)
• 3.9. rokon:: - the ROKON data format (.rokon)
• 3.10. crypto:: - the OS random source

#How to read

#First reading

On a first approach, it is recommended to follow Chapters 0-6 of refs-lang to understand the language's mechanisms, and then read this document on top of that. This document gives meaning to the mechanisms refs-lang defines; without a feel for those mechanisms, the traits and signatures tend to read as if floating in the air. Reading the two documents side by side, moving back and forth, is the most efficient approach.

#As a reference

Each item is identified by a stable section number (<chapter>.<section>). The number is used identically in internal links and external references, so it points reliably even if files move.

refs-standard-libraries 2.3        →  rok ops (Add/Sub/...)
refs-standard-libraries 1.1        →  unsafe Ptr<T>
refs-standard-libraries 3.5.2      →  std io (specific subsection)

#Search

To find a specific trait or function quickly, the lightest approach is to search with ripgrep, narrowing the directory.

rg "trait Add" spec/en/refs-standard-libraries/200-core/
rg "fn into" spec/en/refs-standard-libraries/

#Directory / file naming

This document follows a different directory convention from refs-lang, because the two specifications have different shapes: refs-lang is a flat structure in which chapters 0 through 9 all have equal authority, whereas refs-standard-libraries is a hierarchical structure in which the three tiers act as the key information in cross-references. This structural difference is reflected directly in the number of digits in directory names.

The concrete file naming rules are as follows. Tier directories have prefixes in units of 100, and module files within them start with a three-digit prefix combining one tier digit and two module digits.

Although tier information is encoded in the file path itself, the stable section number (2.3.1, etc.) is the formal notation when citing this document externally. File paths serve only as an auxiliary notation for navigation convenience in IDEs and GitHub.

Edit this page on GitHub