When To Use std.diag
In Zerolang, use std.diag to turn byte offsets into source locations and
small diagnostic snippets without allocating.
Runnable today:
| API | Return | Notes |
|---|---|---|
std.diag.line(bytes, offset) | usize | Returns the 1-based line for a byte offset, clamping offsets past the end. |
std.diag.column(bytes, offset) | usize | Returns the 1-based byte column for a byte offset. |
std.diag.lineStart(bytes, offset) | usize | Returns the byte index where the containing line starts. |
std.diag.lineEnd(bytes, offset) | usize | Returns the byte index where the containing line ends, trimming a trailing CR before LF. |
std.diag.lineText(bytes, offset) | Span<u8> | Borrows the containing line without its newline. |
std.diag.rangeLen(bytes, start, end) | usize | Returns the clamped byte length for a half-open range. |
std.diag.rangeText(bytes, start, end) | Span<u8> | Borrows the clamped half-open byte range. |
std.diag.formatLocation(buffer, path, line, column) | Maybe<Span<u8>> | Writes path:line:column into caller storage. |
std.diag.formatOffsetLocation(buffer, path, bytes, offset) | Maybe<Span<u8>> | Computes line and column from an offset, then writes path:line:column. |
Metadata labels:
- effects: parse for source offset scanning; memory for caller-buffer formatting
- allocation behavior: no allocation, except formatting writes into caller storage
- target support: target-neutral
- error behavior: formatting returns
nullwhen the buffer is too small - ownership notes: text helpers return borrowed views into the input bytes
- example:
conformance/native/pass/std-diag.graph
Example
pub fn main(world: World) -> Void raises { let source: Span<u8> = "one\ntwo\nthree" var storage: [32]u8 = [0_u8; 32] let location: Maybe<Span<u8>> = std.diag.formatOffsetLocation(storage, "input.0", source, 5) if location.has && std.mem.eql(location.value, "input.0:2:2") && std.mem.eql(std.diag.lineText(source, 5), "two") { check world.out.write("diag ok\n") }}Design Notes
Offsets are byte offsets, not Unicode scalar indexes or terminal display columns. That keeps parser diagnostics deterministic and cheap across targets. Line and column numbers are 1-based for user-facing output. Range helpers use half-open byte ranges and clamp both ends to the input length.