Skip to content

CEP-0054: Standard Utility APIs

Draft

Draft proposal for standard-library hash, math, sort, and testing APIs. V1 accepts only minimal math and testing helpers plus namespace ownership.

Summary

Catalyst should eventually define the full std.hash, std.math, std.sort, and std.testing surfaces.

V1 records namespace placement and a small skeleton, but does not design complete utility APIs. The only accepted V1 utility declarations are std.math.min, std.math.max, std.math.clamp, and std.testing.assert.

Example

Possible future shape:

const digest = std.hash.HashMap(String, User).create(allocator)
const root = std.math.sqrt(value)
const q = std.math.div_floor(numerator, denominator)
const r = std.math.mod_euclid(numerator, denominator)
std.sort.sort(i32, items)
std.testing.expect_equal(expected, actual)

The exact API shape is deferred. The proposal owns these utility namespaces so they do not get smuggled into unrelated collection, formatting, or compiler docs.

Motivation

Hashing, math, sorting, and testing are common enough to need stable standard-library ownership. They interact with contracts, numeric semantics, equality/ordering, diagnostics, allocation, and test runner behavior.

Proposed Direction

The proposal should cover:

  • hash contracts, hashers, and hash-map support utilities;
  • math functions, target behavior, and numeric edge cases;
  • alternate integer division and remainder helpers such as floor division, Euclidean division, and Euclidean modulo;
  • sort APIs, ordering requirements, stability, and allocation behavior;
  • testing assertions, fixtures, expected diagnostics, and runner integration;
  • formatting/debug output used by failed test diagnostics;
  • namespace boundaries between these utilities and concrete collections.

V1 Compatibility

V1 does not require or accept complete std.hash, std.math, std.sort, or std.testing APIs.

The active V1 standard-library skeleton accepts:

  • std.math.min, std.math.max, and std.math.clamp for Ord(T) values;
  • std.testing.assert(condition: bool, message: ?[]const u8 = null) as a deterministic assertion trap for tests and examples.

std.hash and std.sort remain namespace skeletons in V1. Hash contracts, hashers, algorithms, alternate integer division and modulo helpers, sorting APIs, comparator policy, equality assertions, fixtures, expected diagnostics, test-runner integration, failed-value formatting, and broader testing policy are deferred to this CEP or a narrower follow-up proposal.