stdlib.core

Core types and runtime glue: Option/Result, allocation, panic and formatting.

Generated from v0.60.1. 4 source files, 145 documented symbols.

cmp.xi

enum Ordering

Three-way comparison result.

• Less
• Equal
• Greater

fn reverse(self: Self) -> Ordering

Swap Less and Greater (Equal is unchanged).

• Postcondition: ?

fn then(self: Self, other: Ordering) -> Ordering

If this is Equal, return other; otherwise keep this ordering.

• Postcondition: self != Equal => result == self

fn then_with(self: Self, f: fn() -> Ordering) -> Ordering

If this is Equal, evaluate f; otherwise keep this ordering.

fn min[T](a: T, b: T) -> T

Smaller of two values.

• Postcondition: result == a || result == b
• Postcondition: result.compare(a) <= 0 && result.compare(b) <= 0

fn max[T](a: T, b: T) -> T

Larger of two values.

• Postcondition: result == a || result == b
• Postcondition: result.compare(a) >= 0 && result.compare(b) >= 0

fn clamp[T](value: T, min_val: T, max_val: T) -> T

Clamp value into [min_val, max_val].

• Precondition: min_val.compare(max_val) <= 0
• Postcondition: result.compare(min_val) >= 0 && result.compare(max_val) <= 0

fn min_by[T](a: T, b: T, compare: fn(&T, &T) -> Ordering) -> T

Value that compares smaller under compare.

fn max_by[T](a: T, b: T, compare: fn(&T, &T) -> Ordering) -> T

Value that compares greater under compare.

fn max_int(a: Int, b: Int) -> Int

Larger of two Ints.

fn min_int(a: Int, b: Int) -> Int

Smaller of two Ints.

fn clamp_int(value: Int, min_val: Int, max_val: Int) -> Int

Clamp an Int into [min_val, max_val].

• Precondition: min_val <= max_val
• Postcondition: min_val <= result <= max_val

fn max_float(a: Float64, b: Float64) -> Float64

Larger of two Float64s.

fn min_float(a: Float64, b: Float64) -> Float64

Smaller of two Float64s.

fn clamp_float(value: Float64, min_val: Float64, max_val: Float64) -> Float64

Clamp a Float64 into [min_val, max_val].

type Reverse

Reverse ordering wrapper

Field	Type
value	T

fn new[T](value: T) -> Reverse[T]

Wrap a value so its ordering is reversed.

fn min3[T](a: T, b: T, c: T) -> T

Minimum of three values. O(1).

fn max3[T](a: T, b: T, c: T) -> T

Maximum of three values. O(1).

fn is_between[T](value: T, lo: T, hi: T) -> Bool

Returns true if value is in the closed interval [lo, hi]. O(1).

fn median3[T](a: T, b: T, c: T) -> T

Median of three values (the value that would be in the middle when sorted). O(1).

fn compare_ints(a: Int, b: Int) -> Int

Compare two integers, returning -1, 0, or 1 like a comparator. O(1).

fn min_of_vec[T](v: &Vec[T]) -> Option[T]

Minimum element in a Vec, or None if empty. O(N).

fn max_of_vec[T](v: &Vec[T]) -> Option[T]

Maximum element in a Vec, or None if empty. O(N).

---

---

contracts.xi

type ContractClause

A single contract clause (requires, ensures, or invariant)

Field	Type
kind	Int
expression	Str
location	Str
function	Str
type_name	Str

Derives: Eq, Clone

type FunctionContracts

All contracts for a function

Field	Type
name	Str
requires	Vec[ContractClause]
ensures	Vec[ContractClause]
return_type	Str
params	Vec[(Str, Str)]

Derives: Clone

type TypeContracts

All contracts for a type

Field	Type
name	Str
invariants	Vec[ContractClause]
fields	Vec[(Str, Str)]

Derives: Clone

type ContractIndex

Complete contract index for a package

Field	Type
package	Str
version	Str
functions	Vec[FunctionContracts]
types	Vec[TypeContracts]
total_clauses	Int
requires_count	Int
ensures_count	Int
invariant_count	Int

Derives: Clone

type ContractCheckResult

Result of a contract check

Field	Type
passed	Bool
clause	ContractClause
actual_values	Map[Str, Str]
message	Str

Derives: Clone

fn verify_invariants[T](value: &T) -> Vec[ContractCheckResult]

Verify ALL invariants of a type against a value at runtime. Returns list of failures (empty = all passed).

• Postcondition: result.len() == 0

fn verify_function_contracts(func: Str, args: Map[Str, Str]) -> Vec[ContractCheckResult]

Verify ALL contracts of a function against its actual call. Called automatically by the compiler at runtime.

fn check_invariant[T](value: &T, invariant: Str) -> ContractCheckResult

Verify a single invariant expression against a value.

fn build_contract_index() -> ContractIndex

Build a complete contract index for the current package. This is what --dump-contracts does at compile time, but available at runtime. REAL: reads function names and requires/ensures counts from the compiler contract table. LIMITED: clause expression text, locations, params, return types and type invariants are not embedded, so those remain empty.

• Postcondition: result.functions.len() >= 0
• Postcondition: result.total_clauses >= 0

fn get_function_contracts(name: Str) -> Option[Vec[FunctionContracts]]

Query contracts for a specific function.

fn get_type_contracts(name: Str) -> Option[Vec[TypeContracts]]

Query contracts for a specific type.

fn find_functions_using_type(type_name: Str) -> Vec[Str]

Find all functions whose contracts reference a given type.

fn find_invariants_using_field(type_name: Str, field_name: Str) -> Vec[ContractClause]

Find all invariants that reference a given field.

fn export_contracts_json() -> Str

Export the contract index as JSON (same format as --dump-contracts).

fn export_contracts_markdown() -> Str

Export the contract index as structured documentation.

fn export_contracts_openapi() -> Str

Export contract index as OpenAPI/Swagger-like spec.

fn reset_contract_coverage()

Track which contracts have been exercised by tests.

fn record_contract_hit(clause: ContractClause, input_values: Map[Str, Str])

Record that clause was exercised with the given inputs.

fn get_contract_coverage() -> Map[Str, Bool]

Map from clause id to whether it has been hit.

fn get_uncovered_contracts() -> Vec[ContractClause]

Clauses that have not been hit yet.

fn coverage_percentage() -> Float64

Percentage of registered clauses that have been hit.

• Postcondition: result >= 0 && result <= 100

fn can_compose(f_requires: Vec[ContractClause], g_ensures: Vec[ContractClause]) -> Str

Given two functions f and g, can g's output satisfy f's requires? Returns the condition that must hold, or "impossible" if never.

fn verify_chain(fns: Vec[Str]) -> Result[Unit, Vec[ContractCheckResult]]

Given a chain of function calls, verify contract propagation.

fn total_contracts() -> Int

Contract Statistics

• Postcondition: result >= 0

fn total_requires() -> Int

Number of registered requires clauses.

fn total_ensures() -> Int

Number of registered ensures clauses.

fn total_invariants() -> Int

Number of registered type invariants.

fn functions_with_contracts() -> Int

Number of functions carrying at least one clause.

fn types_with_invariants() -> Int

Number of types carrying invariants.

fn contract_density() -> Float64

Clauses per function across the registered catalog.

fn none(self: Self) -> Bool

Returns true if the contract index is empty (no functions or types have contracts registered).

• Postcondition: !result => self.functions.len() > 0 || self.types.len() > 0

fn is_sorted(self: Self) -> Bool

Returns true if the functions in the contract index are sorted by name in ascending order. Useful for validating compiler-emitted metadata table ordering.

fn contains_fn(self: Self, name: Str) -> Bool

Returns true if a function with the given name has contracts registered in the index.

fn contains_type(self: Self, name: Str) -> Bool

Returns true if a type with the given name has invariants registered in the index.

fn all_clauses(self: Self) -> Vec[ContractClause]

Returns all contract clauses across all functions (requires + ensures) and types (invariants) in the index. Useful for bulk export or coverage analysis.

• Postcondition: result.len() >= 0

fn filter_nonempty(self: Self) -> ContractIndex

Returns a subset of the contract index containing only functions that have at least one requires or ensures clause. Skips functions with zero clauses.

fn any_contracts() -> Bool

Convenience: check if any contracts exist at all (package-level query).

fn fn_has_contracts(name: Str) -> Bool

Convenience: check if a specific function has contracts (package-level query).

fn type_has_invariants(name: Str) -> Bool

Convenience: check if a specific type has invariants (package-level query).

---

---

core.xi

fn to_int(x: Float64) -> Int

=== Numeric conversions ===

fn to_float(x: Int) -> Float64

Convert an Int to Float64 (may lose precision above 2^53).

fn to_string(x: Int) -> Str

Decimal string for an Int.

fn to_int_from_str(s: Str) -> Result[Int, Str]

Parse an Int; Err with a message on bad input.

• Precondition: true

fn to_float_from_str(s: Str) -> Result[Float64, Str]

Parse a Float64; Err with a message on bad input.

• Precondition: true

fn to_bool_from_str(s: Str) -> Result[Bool, Str]

Parse "true"/"false"; Err on other input.

fn to_char(x: Int) -> Char

Convert a code point to a Char.

fn to_int_from_char(c: Char) -> Int

Code point of a Char as Int.

fn is_sorted[T](items: &Slice[T]) -> Bool

=== Collection contract methods ===

fn all[T](items: &Slice[T], predicate: fn(T) -> Bool) -> Bool

True when every element satisfies predicate (true when empty).

fn none[T](items: &Slice[T], predicate: fn(T) -> Bool) -> Bool

True when no element satisfies predicate.

fn contains[T](items: &Slice[T], value: T) -> Bool

True when value occurs in the slice.

fn deref[T](self: Self) -> &T

Generated summary: Method; Takes no arguments; returns &T. No source comment yet.

• Precondition: ptr != null
• Postcondition: true

fn deref_mut[T](self: Self) -> &mut T

Generated summary: Method; Takes no arguments; returns &mut T. No source comment yet.

• Precondition: ptr != null
• Postcondition: true

fn as_ref[T](self: Self) -> &T

=== M7: AsRef[Str] impl for Str ===

• Precondition: ptr != null

fn as_mut[T](self: Self) -> &mut T

Generated summary: Method; Takes no arguments; returns &mut T. No source comment yet.

• Precondition: ptr != null

fn as_ref(self: Self) -> &Str

Generated summary: Method; Takes no arguments; returns &Str. No source comment yet.

fn as_bytes(self: Self) -> &Slice[UInt8]

=== M7: AsRef<[UInt8]> impl for Str ===

• Precondition: true

enum Cow

8B/M7: Clone-on-Write -- either owned or borrowed

• Borrowed(value: T)
• Owned(value: T)

fn is_borrowed[T](self: Self) -> Bool

Generated summary: Method; Takes no arguments; returns Bool. No source comment yet.

• Postcondition: result == (?)

fn is_owned[T](self: Self) -> Bool

Generated summary: Method; Takes no arguments; returns Bool. No source comment yet.

• Postcondition: result == !self.is_borrowed()

fn to_mut[T](self: Self) -> &mut T

Generated summary: Method; Takes no arguments; returns &mut T. No source comment yet.

• Postcondition: true

fn into_owned[T](self: Self) -> T

Generated summary: Method; Takes no arguments; returns T. No source comment yet.

• Postcondition: true

fn borrow[T](self: Self) -> &T

Generated summary: Method; Takes no arguments; returns &T. No source comment yet.

• Postcondition: true

fn from(value: Float64) -> Int

Int -> Float64 (lossless for reasonable values)

fn into(self: Self) -> Int

Truncating conversion to Int.

fn from(value: Int) -> Float64

Float64 -> Int (may truncate)

fn into(self: Self) -> Float64

Widening conversion to Float64 (lossy above 2^53).

fn from(value: Int) -> Str

Int -> Str

fn into(self: Self) -> Str

Decimal string conversion.

fn from(value: Float64) -> Str

Float64 -> Str

fn into(self: Self) -> Str

Decimal string conversion.

fn from(value: Bool) -> Str

Bool -> Str

fn into(self: Self) -> Str

"true" or "false" conversion.

fn from(value: Bool) -> Int

Bool -> Int

fn into(self: Self) -> Int

1 for true, 0 for false.

fn from(value: Char) -> Int

Char -> Int

fn into(self: Self) -> Int

Unicode code point conversion.

fn from(value: Int) -> Char

Int -> Char (may fail, returns first char)

fn into(self: Self) -> Char

Char for the code point (invalid values map to U+FFFD).

fn size_of[T]() -> Int

=== Type-level operations === Compiler intrinsic: returns size of type in bytes

fn align_of[T]() -> Int

Compiler intrinsic: returns alignment of type in bytes

type PhantomData

8B/M7: Zero-size type marker for generic parameters

Field	Type

type MaybeUninit

8B/M7: Uninitialized memory container

Field	Type
data	T
initialized	Bool

Derives: Clone

fn uninit[T]() -> MaybeUninit[T]

Generated summary: Takes no arguments; returns MaybeUninit[T]. No source comment yet.

• Postcondition: !result.initialized

fn new[T](value: T) -> MaybeUninit[T]

Generated summary: takes value: T; returns MaybeUninit[T]. No source comment yet.

• Postcondition: result.initialized

fn assume_init[T](self: Self) -> T

Generated summary: Method; Takes no arguments; returns T. No source comment yet.

• Precondition: self.initialized
• Postcondition: true

fn write[T](self: Self, value: T)

Generated summary: Method; takes value: T; returns nothing. No source comment yet.

• Postcondition: self.initialized == true
• Postcondition: self.data == value

fn min_of(a: Int, b: Int) -> Int

Returns the smaller of two Int values. Complexity: O(1). Pure, no side effects.

fn max_of(a: Int, b: Int) -> Int

Returns the larger of two Int values. Complexity: O(1). Pure, no side effects.

fn abs_int(n: Int) -> Int

Returns the absolute value of n. Complexity: O(1). Pure, no side effects. NOTE: INT_MIN has no positive representation; wraps on overflow.

fn clamp_int(v: Int, lo: Int, hi: Int) -> Int

Clamps v to the inclusive range [lo, hi]. Returns lo if v < lo, hi if v > hi, otherwise v. Complexity: O(1). Pure, no side effects.

fn bool_to_int(b: Bool) -> Int

Converts a Bool to an Int: true -> 1, false -> 0. NOTE: XIOM does NOT support b as Int; this is the canonical conversion. Complexity: O(1). Pure, no side effects.

fn int_to_bool(n: Int) -> Bool

Converts an Int to a Bool: non-zero -> true, zero -> false. Complexity: O(1). Pure, no side effects.

fn int_to_char_safe(n: Int) -> Option[Char]

Safely converts an Int to a Char. Returns None if n is outside the valid Unicode code-point range (0..=0x10FFFF). Complexity: O(1). Pure, no side effects.

fn slice_len[T](s: &Slice[T]) -> Int

Returns the number of elements in the slice. Complexity: O(1). Thread-safe: reads immutable shared data.

fn slice_is_empty[T](s: &Slice[T]) -> Bool

Returns true if the slice has zero elements. Complexity: O(1). Thread-safe: reads immutable shared data.

fn slice_first[T](s: &Slice[T]) -> Option[T]

Returns the first element of the slice, or None if empty. Complexity: O(1). Thread-safe: reads immutable shared data.

fn slice_get[T](s: &Slice[T], i: Int) -> Option[T]

Returns the element at index i, or None if out of bounds. Complexity: O(1). Thread-safe: reads immutable shared data.

fn slice_to_vec[T](s: &Slice[T]) -> Vec[T]

Copies all elements from the slice into a new Vec[T]. Complexity: O(n) time and memory. Thread-safe: reads immutable shared data.

fn min_slice[T](s: &Slice[T]) -> Option[T]

Finds the minimum element in the slice using Ord.compare. Returns None if the slice is empty. Complexity: O(n) comparisons. Thread-safe: reads immutable shared data.

fn max_slice[T](s: &Slice[T]) -> Option[T]

Finds the maximum element in the slice using Ord.compare. Returns None if the slice is empty. Complexity: O(n) comparisons. Thread-safe: reads immutable shared data.

fn sum_slice(s: &Slice[Int]) -> Int

Sums all Int elements in the slice. Returns 0 if the slice is empty. Complexity: O(n). Thread-safe: reads immutable shared data.

fn option_is_some[T](o: &Option[T]) -> Bool

Returns true if the option is Some. Complexity: O(1). Thread-safe: reads immutable shared data.

fn option_is_none[T](o: &Option[T]) -> Bool

Returns true if the option is None. Complexity: O(1). Thread-safe: reads immutable shared data.

fn result_is_ok[T, E](r: &Result[T, E]) -> Bool

Returns true if the result is Ok. Complexity: O(1). Thread-safe: reads immutable shared data.

fn result_is_err[T, E](r: &Result[T, E]) -> Bool

Returns true if the result is Err. Complexity: O(1). Thread-safe: reads immutable shared data.

fn result_unwrap_or[T, E](r: Result[T, E], default: T) -> T

Returns the contained Ok value, or default if the result is Err. Complexity: O(1). Thread-safe: reads immutable shared data.

---

---

platform.xi

fn os_name() -> Str

Return the operating system name as a lowercase string. Delegates to xiom.env.OS (compile-time constant). Possible values: "windows", "linux", "macos", "freebsd", "openbsd", "unknown".

• Postcondition: result.len() > 0

fn is_windows() -> Bool

True when the target OS is Windows.

fn is_linux() -> Bool

True when the target OS is Linux.

fn is_macos() -> Bool

True when the target OS is macOS (Darwin).

fn is_bsd() -> Bool

True when the target OS is a BSD variant (freebsd, openbsd, netbsd).

fn is_unix() -> Bool

True when the target OS is a Unix-like system (Linux, macOS, BSD). This is the negation of is_windows().

fn arch_name() -> Str

Return the CPU architecture name as a lowercase string. Delegates to xiom.env.ARCH (compile-time constant). Possible values: "x86_64", "aarch64", "riscv64", etc. If no intrinsic is available, returns "unknown".

• Postcondition: result.len() > 0

fn endian_is_little() -> Bool

Returns true if the current platform is little-endian. On x86_64 and aarch64 (which dominate current hardware), this is always true. For a full runtime check, a known integer pattern would be inspected via pointer casting, but the XIOM compiler currently lacks raw pointer deref. Documented as: true on all current XIOM targets (x86_64, aarch64).

fn page_size() -> Int

Return the system page size in bytes (typically 4096). No cross-platform FFI intrinsic exists yet; returns the most common value.

• Postcondition: result > 0

fn cpu_count() -> Int

Return the number of logical CPU cores available. Delegates to xiom.os.cpu_count() (which calls xiom_cpu_count runtime function).

• Postcondition: result >= 1

fn newline() -> Str

Return the platform-specific newline sequence. Returns "\r\n" on Windows, "\n" everywhere else.

• Postcondition: result.len() > 0

fn path_sep() -> Str

Return the platform-specific path separator. Returns "\" on Windows, "/" everywhere else.

• Postcondition: result.len() > 0

fn is_64bit() -> Bool

Returns true if the platform uses 64-bit pointers. XIOM Int is always 64-bit, so this is always true.

fn os_version() -> Str

Return the operating system version string. Best-effort: reads environment variables or delegates to OS-specific APIs. On Windows: attempts "OS" or "VER" environment variable. On Unix: attempts "OSTYPE" or returns "unknown". Returns "unknown" if no version information is available.

---

---