silk/uri_reference

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Borrowed RFC 3986 URI references, explicit owned storage, and lossless component views.

When to use

Use parse for a URI or a relative reference. Use silk.uri when a scheme is required.

Details

parse borrows its input without allocation. OwnedUriReference provides explicit owned storage. Empty components remain distinct from absent components. Parsing does not decode percent escapes.

Gotchas

This module checks generic URI syntax. It does not apply scheme, network, or identity policy. Raw non-ASCII bytes and IPv6 zone identifiers are not RFC 3986 syntax.

Import as UriReference with import silk.uri_reference { UriReference }.

Public declarations: 6.

HostKind

pub enum HostKind

The RFC grammar that matches an authority host.

RegName

RegName = 0

A registered name, including an empty host.

Ipv4

Ipv4 = 1

Four decimal octets with no leading zero in a multi-digit octet.

Ipv6

Ipv6 = 2

A bracketed IPv6 address without a zone identifier.

IpvFuture

IpvFuture = 3

A bracketed future IP literal with a hexadecimal version.

Component

pub enum Component

The URI component in which syntax validation fails.

Scheme

Scheme = 0

The scheme before its colon.

Authority

Authority = 1

The authority after two slashes.

Userinfo

Userinfo = 2

The user information before its at sign.

Host

Host = 3

The registered name or IP literal.

Port

Port = 4

The decimal port after its colon.

Path

Path = 5

The path before a query or fragment delimiter.

Query

Query = 6

The query after its question mark.

Fragment

Fragment = 7

The fragment after its number sign.

ParseReason

pub enum ParseReason

A generic URI syntax failure category.

InvalidCharacter

InvalidCharacter = 0

A byte is not allowed in the selected component.

InvalidPercentEscape

InvalidPercentEscape = 1

A percent sign is not followed by two hexadecimal digits.

InvalidScheme

InvalidScheme = 2

A scheme is empty or does not follow the scheme grammar.

InvalidHost

InvalidHost = 3

An IP literal or host delimiter does not follow the host grammar.

InvalidPort

InvalidPort = 4

A port contains a non-decimal byte.

MissingScheme

MissingScheme = 5

A scheme-bearing URI was requested but the input has no scheme.

ParseError

pub struct ParseError

A syntax failure with its component and original byte position.

Field reason

pub reason: ParseReason

The failed syntax rule.

Field component

pub component: Component

The component that contains the failure.

Field offset

pub offset: usize

The zero-based offending byte offset, or the end offset when required syntax is missing.

Implementation Copy for ParseError

impl Copy for ParseError

UriReference

pub struct UriReference<'text>

An immutable parsed reference borrowing its original serialization.

Details

Parsing allocates nothing. The result and its component views cannot outlive the input. Use copy to retain the value independently, or OwnedUriReference.fromString to adopt text.

Associated function UriReference.parse

pub fn parse<'text>(text: string<'text>) -> silk/result.Result<silk/uri_reference.UriReference<'text>, silk/uri_reference.ParseError>

Validates and borrows a URI reference without allocating or normalizing.

Details

Syntax errors identify the failed component and byte. Valid dotted decimal hosts take precedence over registered names. The result retains the lifetime of text.

Associated function UriReference.validateComponent

pub fn validateComponent<'life1>(text: string<'life1>, component: Component) -> silk/option.Option<silk/uri_reference.ParseError>

Validates the encoded grammar of one component without allocating.

Details

Errors are relative to the supplied component text. Path checks its allowed bytes; assembly must additionally check path form against the presence of scheme and authority. Host accepts bracketed literals or reg-names, never userinfo or a port. Empty ports and hosts are valid.

Method UriReference.copy

pub effect<'env> fn copy<'text: 'env, 'life1: 'env, 'env>(self: &'life1 UriReference<'text>) -> OwnedUriReference ! OutOfMemoryError ? &mut Allocator

Copies a parsed reference into independent owned storage with one allocation for nonempty input.

Associated function UriReference.parseOwned

pub effect<'text> fn parseOwned<'text>(text: string<'text>) -> silk/result.Result<silk/uri_reference.OwnedUriReference, silk/uri_reference.ParseError> ! OutOfMemoryError ? &mut Allocator

Validates input and explicitly copies it into owned storage; invalid input does not allocate.

Method UriReference.format

pub fn format<'text, 'life1>(self: &'life1 UriReference<'text>) -> string<'text>

Returns the original borrowed serialization, preserving all delimiters and escape spelling.

Method UriReference.scheme

pub fn scheme<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows the scheme without its colon, or returns None for a relative reference.

Method UriReference.authority

pub fn authority<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows the authority without its two slashes, including a present empty authority.

Method UriReference.userinfo

pub fn userinfo<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows user information without its at sign, or returns None when absent.

Details

An empty value is present. Colons remain part of the value; no username or password split occurs.

Method UriReference.host

pub fn host<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows the host with IP-literal brackets intact, or returns None when authority is absent.

Details

An empty authority has a present empty host. The view borrows from the input without allocation.

Method UriReference.port

pub fn port<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows the decimal port without its colon, or returns None when the colon is absent.

Details

An empty port is present. This operation does not convert the port to a number or impose a limit.

Method UriReference.path

pub fn path<'text, 'life1>(self: &'life1 UriReference<'text>) -> string<'text>

Borrows the path from the input without allocation; an empty path returns an empty string.

Method UriReference.query

pub fn query<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows the query without its question mark, including a present empty query.

Method UriReference.fragment

pub fn fragment<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<string<'text>>

Borrows the fragment without its number sign, including a present empty fragment.

Method UriReference.hostKind

pub fn hostKind<'text, 'life1>(self: &'life1 UriReference<'text>) -> silk/option.Option<silk/uri_reference.HostKind>

Returns the host grammar classification, or None when authority is absent.

Implementation Copy for silk/uri_reference.UriReference<'text>

impl Copy for silk/uri_reference.UriReference<'text>

OwnedUriReference

pub struct OwnedUriReference

An immutable owner of validated URI-reference text and scalar component ranges.

Details

Owns no references into itself. view borrows existing storage without reparsing or allocating. Use fromString to transfer existing storage, or UriReference.parseOwned to copy input.

Associated function OwnedUriReference.fromString

pub fn fromString(text: String) -> silk/result.Result<silk/uri_reference.OwnedUriReference, silk/uri_reference.ParseError>

Validates and adopts an existing String without copying or allocating.

Gotchas

This operation consumes the String on both success and syntax failure.

Method OwnedUriReference.view

pub fn view<'life0>(self: &'life0 OwnedUriReference) -> silk/uri_reference.UriReference<'life0>

Borrows a parsed reference from this owner's stored ranges without validation or allocation.

Method OwnedUriReference.intoString

pub fn intoString(self: OwnedUriReference) -> String

Transfers the original owned serialization out of the parsed owner without copying.