wehub-resource-sync
e7738de6d2
CI / Deep Native Runtime Cases (1/6) (push) Has been skipped
CI / Native Preflight (push) Failing after 1s
CI / Native Runtime Cases (1/2) (push) Failing after 0s
CI / Native Runtime Cases (2/2) (push) Failing after 1s
CI / Native Metadata Reports (push) Failing after 0s
CI / Native Direct Backend Artifacts (push) Failing after 0s
CI / Native Sanitizer Smoke (push) Failing after 1s
CI / Command Contract Snapshots (push) Failing after 1s
CI / Deep Conformance Suite (push) Has been skipped
CI / Graph Build Perf (push) Failing after 1s
CI / Deep Native Preflight (push) Has been skipped
CI / Deep Native Runtime Cases (2/6) (push) Has been skipped
CI / Deep Native Runtime Cases (3/6) (push) Has been skipped
CI / Conformance Suite (push) Failing after 1s
CI / Workspace Checks (push) Failing after 0s
CI / Deep Native Runtime Cases (5/6) (push) Has been skipped
CI / Deep Native Runtime Cases (6/6) (push) Has been skipped
CI / Deep Native Runtime Cases (4/6) (push) Has been skipped
CI / Deep Graph Build Perf (push) Has been skipped
48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
## 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
|
|
|
|
```zero
|
|
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.
|