std.url

URL.parse takes a string and applies the WHATWG URL parser with UTF-8 input and no base URL. A successful parse returns Ok containing an immutable URL. Relative references need a base and therefore return Err.

A parser failure returns Err containing a nonempty string. Missing or invalid schemes, invalid hosts, and ports outside 0 through 65535 fail. Error wording is explanatory text and has no fixed spelling.

URL preprocessing removes leading and trailing code points from U+0000 through U+0020. It then removes U+0009, U+000A, and U+000D throughout the input. Other characters are processed by the URL parser. A validation warning that permits parsing does not become an Err.

Schemes use lowercase. Special-scheme domain hosts use ASCII domain serialization. Default ports disappear and hierarchical dot segments are removed. Opaque paths retain their distinct path interpretation.

The default ports are 21 for ftp, 80 for http and ws, and 443 for https and wss. Other valid ports survive serialization as decimal integers. The file scheme has no port.

URL.toString serializes every stored component. It preserves user information, nondefault ports, query order, and explicit empty query and fragment delimiters. Existing percent escapes retain their spelling. Newly escaped characters use percent-encoded UTF-8 bytes with uppercase hexadecimal digits.

Parsing the serialization produces the same serialization and component values. Reading a URL does not modify it. Parsing evaluates its argument once before validation and performs no network or filesystem operation.

URL.scheme returns the lowercase scheme without its delimiter. URL.host returns Some containing the serialized host without user information or a port. IPv6 hosts include their square brackets.

A URL whose host is absent returns None() from URL.host. A present empty host returns Some containing an empty string. A local file URL can have that empty host.

URL.path returns the serialized path without the query or fragment. A hierarchical path retains its leading slash. An opaque path has no implied slash. Percent escapes stay encoded so an escaped slash remains path data.

URL.fragment returns None() when there is no fragment delimiter. An explicit empty fragment returns Some containing an empty string. A present fragment excludes its delimiter and retains percent encoding.

Scheme, host, path, and fragment inspection cannot fail after construction. Each receiver is evaluated once. The returned strings are immutable and inspection has no external effects.

Read URL.query for decoded query fields. URL.path and URL.fragment do not apply query decoding. In particular, a plus sign in those components remains a plus sign.

URL.query returns a new Map from decoded names to arrays of decoded values. A missing query and an empty query both produce an empty map.

Query decoding follows application/x-www-form-urlencoded parsing. Ampersands separate fields. Empty fields between separators are skipped. The first equals sign separates each name from its value. A field without that sign has an empty value.

An explicit empty name is retained. A plus sign decodes to an ASCII space. Valid percent escapes decode to bytes and those bytes decode as UTF-8. Malformed percent escapes remain literal text and invalid UTF-8 sequences use the replacement character.

Repeated names are grouped after decoding. Values retain encounter order. Map keys retain the order in which their decoded names first appear. No sorting, deduplication, or comma splitting occurs.

The returned Map and its value arrays follow collection value semantics →. URL.toString preserves the stored serialized query rather than serializing this map.

Reading a query evaluates its receiver once and performs no external operation. A constructed URL can always produce its query map. Query decoding does not return a diagnostic or a Result error.