vercel-labs--zerolang/docs/articles/modules/diag.md

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 null when 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.