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

When To Use std.parse

In Zerolang, use std.parse for allocation-free byte scanners and scalar parsers.

Runnable today:

API	Return	Notes
std.parse.isAsciiDigit(value)	Bool	Checks whether the first byte is 0 through 9.
std.parse.isAsciiAlpha(value)	Bool	Checks whether the first byte is ASCII alphabetic.
std.parse.isIdentifierStart(value)	Bool	Checks whether the first byte can start a Zero identifier.
std.parse.isWhitespace(value)	Bool	Checks ASCII whitespace.
std.parse.scanDigits(value)	usize	Counts a leading run of ASCII digits.
std.parse.scanIdentifier(value)	usize	Counts a leading identifier token.
std.parse.scanWhitespace(value)	usize	Counts leading spaces, tabs, line feeds, and carriage returns.
std.parse.scanUntilByte(value, byte)	usize	Returns the first matching byte index or the input length.
std.parse.tokenAscii(value)	Span<u8>	Borrows the first non-whitespace ASCII token.
std.parse.parseBool(value)	Maybe<Bool>	Parses true or false.
std.parse.parseDuration(value)	Maybe<Duration>	Parses signed ns, us, ms, s, m, and h duration components such as 1h30m.
std.parse.parseByteSize(value)	Maybe<usize>	Parses bytes plus KB, MB, GB, KiB, MiB, and GiB suffixes.
std.parse.parseI32(value)	Maybe<i32>	Parses a full signed 32-bit decimal value.
std.parse.parseI32Base(value, base)	Maybe<i32>	Parses a full signed 32-bit value in base 2 through 36.
std.parse.parseI32Prefix(value)	Maybe<i32>	Parses signed decimal, 0x, 0o, or 0b input.
std.parse.parseI64(value)	Maybe<i64>	Parses a full signed 64-bit decimal value.
std.parse.parseI64Base(value, base)	Maybe<i64>	Parses a full signed 64-bit value in base 2 through 36.
std.parse.parseI64Prefix(value)	Maybe<i64>	Parses signed decimal, 0x, 0o, or 0b input.
std.parse.parseU8(value)	Maybe<u8>	Parses a full decimal byte value.
std.parse.parseU16(value)	Maybe<u16>	Parses a full decimal unsigned 16-bit value.
std.parse.parseU32(value)	Maybe<u32>	Parses a full decimal unsigned 32-bit value.
std.parse.parseU32Base(value, base)	Maybe<u32>	Parses a full unsigned 32-bit value in base 2 through 36.
std.parse.parseU32Prefix(value)	Maybe<u32>	Parses unsigned decimal, 0x, 0o, or 0b input.
std.parse.parseU64(value)	Maybe<u64>	Parses a full decimal unsigned 64-bit value.
std.parse.parseU64Base(value, base)	Maybe<u64>	Parses a full unsigned 64-bit value in base 2 through 36.
std.parse.parseU64Prefix(value)	Maybe<u64>	Parses unsigned decimal, 0x, 0o, or 0b input.
std.parse.parseUsize(value)	Maybe<usize>	Parses a full decimal usize value.
std.parse.parseUsizeBase(value, base)	Maybe<usize>	Parses a full usize value in base 2 through 36.
std.parse.parseUsizePrefix(value)	Maybe<usize>	Parses usize decimal, 0x, 0o, or 0b input.

Current limits:

• Source position and span types.
• Rich cursor objects beyond the current allocation-free scanner primitives.
• Token and diagnostic data shared by language and data parsers.

Example

use std.parse

pub fn main(world: World) -> Void raises {
    let digit: Bool = std.parse.isAsciiDigit("7")
    let ident: Bool = std.parse.isIdentifierStart("_")
    let scanned: usize = std.parse.scanDigits("123abc")
    let parsed: Maybe<u16> = std.parse.parseU16("8080")
    let signed: Maybe<i32> = std.parse.parseI32Prefix("-0x2a")
    let signed64: Maybe<i64> = std.parse.parseI64("-9223372036854775808")
    let hex: Maybe<u32> = std.parse.parseU32Base("ff", 16_u32)
    let hex64: Maybe<u64> = std.parse.parseU64Prefix("0xffffffffffffffff")
    let duration: Maybe<Duration> = std.parse.parseDuration("1h30m")
    let size: Maybe<usize> = std.parse.parseByteSize("2MiB")
    let token: Span<u8> = std.parse.tokenAscii("  zero text")
    if digit && ident && scanned == 3 && parsed.has && parsed.value == 8080 && signed.has && signed.value == -42 && signed64.has && signed64.value == 0 - 9223372036854775807 - 1 && hex.has && hex.value == 255_u32 && hex64.has && hex64.value == 18446744073709551615_u64 && duration.has && std.time.asSecondsFloor(duration.value) == 5400_i64 && size.has && size.value == 2097152 && std.mem.eql(token, "zero") {
        check world.out.write("parse primitives ok\n")
    }
}

Design Notes

The module stays byte-oriented so compiler, config, and codec code can parse without Unicode scalar handling or heap allocation. Public helpers accept byte spans, so callers can parse string literals, fixed arrays, and runtime buffers.

Integer parsers return Maybe<T> instead of allocating diagnostics. Base parsers accept bases 2 through 36, consume the full input, and reject overflow. Prefix parsers recognize decimal by default plus 0x, 0o, and 0b for 32-bit, 64-bit, and usize widths. Duration and byte-size parsers also consume the full input and reject overflow.