CEP-0048: Standard Text and Formatting¶

Summary¶

Catalyst should eventually define the full standard-library text and formatting surface.

V1 keeps only namespace placement and expected ownership boundaries for std.text, std.fmt, std.debug, and std.io. String literals remain []const u8 byte sequences.

Example¶

Possible future shape:

fn write_level(out: *impl std.io.Writer, level: i32) void! {
  try std.fmt.write(out, "level={}", level)
}

var builder = std.text.Builder.create(allocator)
try builder.write("level=")
try std.fmt.write(builder.writer(), "{}", level)

const text = builder.to_string()

The proposal must define ownership, encoding, allocation, formatting contracts, debug rendering, and IO sink behavior. IO sinks, including stdout and stderr, should be modeled as explicit capabilities rather than ambient output authority.

Motivation¶

Text and formatting APIs cut across allocation, encoding, IO, diagnostics, debug rendering, and documentation. They need a coherent standard-library design rather than ad hoc helpers.

Proposed Direction¶

The proposal should cover:

• owned strings and builders;
• string views or encoding-specific helpers;
• formatting contracts and renderers;
• debug rendering contracts;
• printing APIs and IO sink integration;
• stdout, stderr, and other process streams as explicit IO capabilities;
• allocation and error behavior.

V1 Compatibility¶

V1 does not require or accept full text, formatting, debug, or IO APIs. The active V1 standard-library skeleton reserves these namespaces but does not define std.text.String, builders, UTF-8 validation helpers, formatting contracts, debug rendering contracts, readers, writers, print, or println.

V1 string literals have type []const u8. Direct source text and \u{...} escapes contribute UTF-8 bytes, while \xNN escapes may produce arbitrary bytes that are not valid UTF-8.

Related Details¶

• std.text
• std.fmt
• std.debug
• std.io