std.url

import std.url parses and formats absolute URLs, percent-encodes data for a named URL component, and splits and builds query strings. It has one error type, UrlError.

The module is checked Plenty code over std.bytes, with no native primitives of its own. It is available on the supported x86-64 Linux GNU target. A URL is not a filesystem path: std.path is a separate type and nothing converts between them.

import std.url
from std.url import Component, Pair, UrlError

def main() -> Result[(), AllocError | IoError | UrlError]:
    url = std.url.parse("https://example.com:8443/search?q=caf%C3%A9&page=2#top", 2048)?
    print(url.scheme, url.host, url.port, url.path)?
    match &url.query:
        case Some(query):
            for pair in std.url.query_pairs(query)?:
                print(pair.key, "=", pair.value)?
        case Nothing:
            print("no query")?
    print(std.url.encode("a b/c", Component.Segment)?)?
    print(std.url.query_text(&[Pair("q", "fish & chips"), Pair("n", "1")]?)?)?
    Ok(())

https Option[str].Some("example.com") Option[i64].Some(8443) /search
q = café
page = 2
a%20b%2Fc
q=fish%20%26%20chips&n=1

The accepted syntax

std.url implements the generic syntax of RFC 3986, with these stated differences. It is not the WHATWG URL Standard and does not imitate browsers.

Because nothing is normalized and the port has one spelling, every accepted URL formats back to the identical text.

Url

pub class Url:
    pub scheme: str
    pub userinfo: Option[str]
    pub host: Option[str]
    pub port: Option[i64]
    pub path: str
    pub query: Option[str]
    pub fragment: Option[str]

Components hold the text between the delimiters, still percent-encoded and without the delimiters themselves. Nothing means the delimiter was absent; Some("") means it was present with nothing after it, so s:, s:?, and s:// are three different values. host is Nothing exactly when the URL has no // authority. An address literal keeps its brackets: [::1].

parse checks the length first: LimitExceeded for a longer text. It then reports the first violation from left to right.

to_string exists so that a Url built or edited by a program cannot produce text that parses differently. It applies the rules of parse to each field, and also returns:

• MissingHost when userinfo or port is present without host;
• InvalidPort when port is outside 0 to 65535;
• InvalidByte when host is present and a nonempty path does not start with /, or host is absent and path starts with //.

A successful to_string result always parses back to equal components.

Compare URLs only after deciding what equivalence means for your scheme. The module does not lowercase schemes or hosts and does not decode escapes, so HTTP://A/%7e and http://a/~ are different values.

Percent encoding

Ranges follow the std.bytes range rule.

Letters, digits, and -._~ are never escaped. % is always escaped, so encoding text that already contains escapes encodes it again. Escapes are written with uppercase hex digits. Each Component additionally keeps:

Userinfo output is also valid in a registered host name.

Decoding is the same for every component: %hh becomes one byte and every other byte is copied. + stays +; the application/x-www-form-urlencoded reading of + as a space is not implemented. decode returns InvalidUtf8 when the bytes are not UTF-8; use decode_bytes for binary data.

Decoded text can contain any character, including /, ?, NUL, and line breaks. Split a URL into components before decoding, and never parse decoded text as a URL or a path.

Query strings

pub class Pair:
    pub key: str
    pub value: str

Every &-separated piece is one pair, in order, including empty pieces and repeated keys. A piece without = has an empty value, so a and a= read the same; query_text always writes the =. The empty query has no pairs. query_pairs accepts any byte that is not part of a malformed escape; pass it a Url.query to get the stricter component check.

Errors

pub enum UrlError:
    LimitExceeded
    MissingScheme
    MissingHost
    InvalidByte(i64)
    InvalidEscape(i64)
    InvalidHost(i64)
    InvalidPort(i64)
    InvalidUtf8
    Allocation(AllocError)

An index is a UTF-8 byte offset into the input. For to_string it is an offset into the text that would have been produced; for the byte-range functions it is a position in the source buffer, not relative to start. A failed operation releases anything it allocated. Wrap a result with std.error.context to name the operation.

Ownership and threads

Url and Pair own their strings, so they are resources: assignment moves them, and the ordinary loan rules apply to their fields. All inputs are shared loans. The module holds no global state; its functions pass the ordinary worker-effect checks and may run in any thread.

Costs

Every operation is linear in its input and allocates in proportion to it.

Encoded output is at most three times its input. The encoder counts literal bytes, then checks 3 * escaped + literals before allocating its result. Unrepresentable output sizes are Allocation(AllocError.CapacityOverflow). Parser, decoder and query cursors use documented bounds-proven arithmetic; terminal literal runs and final query pairs stop at the input endpoint instead of advancing past it. A serializer error offset that cannot fit i64 also returns allocation-capacity overflow. Caller arithmetic modes do not change these contracts.

Every byte goes through checked single-element Bytes calls, several times per byte. An earlier release-compiler measurement, before checked-default adoption, on x86-64 Linux pinned to one core found that parsing one 91-byte URL with all seven components took about 49 µs: roughly half a microsecond per input byte.

Limits

• No relative references and no reference resolution (RFC 3986 section 5).
• No normalization or equivalence: no case folding, dot-segment removal, escape normalization, or default-port knowledge.
• No IDNA or Punycode conversion, and no scheme-specific rules such as http requiring a host.
• No IPv6 zone identifiers. IPv4 addresses are not distinguished from registered names.
• No form encoding (+ as a space) and no ; pair separator.
• Query pairs are a list. There is no keyed lookup helper; scan the list.