silk/uri_components

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.

Mutable URI components with explicit raw-byte encoding and selective serialization.

When to use

Use UriComponents to construct a reference or modify components borrowed from an existing one. Use silk.uri_reference.UriReference.parse to inspect complete serialized input.

Details

Raw component bytes are percent encoded. Encoded component text retains its escape spelling. Serialization validates component boundaries before changing output. Owned construction adopts the completed serialization without another copy.

Import as UriComponents with import silk.uri_components { UriComponents }.

Public declarations: 5.

ComponentValue

pub union ComponentValue<'text>

Component data that explicitly selects raw-byte encoding or existing encoded text.

Raw

ComponentValue<'text>.Raw { bytes: &'text [u8] }: ComponentValue<'text>

Raw bytes that are encoded according to the selected URI component grammar.

Field bytes

pub bytes: &'text [u8]

The bytes to encode; percent signs are data and are escaped again.

Encoded

ComponentValue<'text>.Encoded { text: string<'text> }: ComponentValue<'text>

Already encoded text whose valid percent escapes retain their original spelling.

Field text

pub text: string<'text>

The text to validate before serialization; delimiters for other components are rejected.

Host

pub union Host<'text>

An authority host with an explicit distinction between names and bracketed IP literals.

RegName

Host<'text>.RegName { value: silk/uri_components.ComponentValue<'text> }: Host<'text>

A registered name or dotted decimal host; raw bytes use registered-name encoding.

Field value

pub value: silk/uri_components.ComponentValue<'text>

The raw or encoded host name, including an empty name.

IpLiteral

Host<'text>.IpLiteral { text: string<'text> }: Host<'text>

A bracketed IPv6 or IPvFuture literal that must already satisfy the host grammar.

Field text

pub text: string<'text>

The complete literal, including its opening and closing brackets.

Authority

pub struct Authority<'text>

Structured authority data with unsplit user information and a lexical decimal port.

Field userinfo

pub userinfo: silk/option.Option<silk/uri_components.ComponentValue<'text>>

Optional user information; a present empty value emits an at sign.

Field host

pub host: silk/uri_components.Host<'text>

The registered name or bracketed IP literal.

Field port

pub port: silk/option.Option<string<'text>>

Optional decimal text; a present empty value emits a colon without digits.

Serialization

pub enum Serialization

The components to include in a serialization.

Full

Full = 0

Every component, preserving present empty delimiters.

WithoutAuthentication

WithoutAuthentication = 1

Every component except user information and its at sign.

PathAndQuery

PathAndQuery = 2

Only the path and optional query, without scheme, authority, or fragment.

UriComponents

pub struct UriComponents<'text>

Mutable URI-reference components borrowing their raw bytes or encoded text.

Details

Modify public fields to construct another reference. No component owns its input storage. An absent component differs from a present empty component. The path is always present.

Field scheme

pub scheme: silk/option.Option<string<'text>>

An optional scheme without its colon.

Field authority

pub authority: silk/option.Option<silk/uri_components.Authority<'text>>

An optional structured authority without its two slashes.

Field path

pub path: silk/uri_components.ComponentValue<'text>

The complete raw or encoded path, including any separating slashes.

Field query

pub query: silk/option.Option<silk/uri_components.ComponentValue<'text>>

An optional raw or encoded query without its question mark.

Field fragment

pub fragment: silk/option.Option<silk/uri_components.ComponentValue<'text>>

An optional raw or encoded fragment without its number sign.

Associated function UriComponents.make

pub fn make<'text>() -> silk/uri_components.UriComponents<'text>

Creates an empty relative reference without allocating.

Associated function UriComponents.fromReference

pub fn fromReference<'text, 'life1>(reference: &'life1 silk/uri_reference.UriReference<'text>) -> silk/uri_components.UriComponents<'text>

Borrows every parsed component as encoded text for inspection or modification without allocating.

Details

Serialization with Full preserves the original text when no fields have changed.

Associated function UriComponents.serializeInto

pub effect<'env> fn serializeInto<'text: 'env, 'life1: 'env, 'life2: 'env, 'env>(output: &'life1 mut silk/bytes.Bytes, self: &'life2 UriComponents<'text>, selection: Serialization) -> silk/result.Result<(), silk/uri_reference.ParseError> ! OutOfMemoryError ? &mut Allocator

Replaces reusable output with validated selected components.

Details

Component errors report offsets within the supplied component and leave output unchanged. Size overflow and allocation failure also leave output unchanged. Existing sufficient capacity is reused. Full output is reparsed without allocation; any recomposition error reports an output offset. Raw first-relative-segment colons are escaped so they cannot introduce a scheme.

Gotchas

A recomposition error leaves the attempted serialization in output. PathAndQuery can produce text that is not a complete URI reference. Omitted components are still validated.

Method UriComponents.serializeOwned

pub effect<'env> fn serializeOwned<'text: 'env, 'life1: 'env, 'env>(self: &'life1 UriComponents<'text>, selection: Serialization) -> silk/result.Result<silk/string.String, silk/uri_reference.ParseError> ! OutOfMemoryError ? &mut Allocator

Serializes selected components into independent text with one exact allocation for nonempty output.

Details

Validation errors return ordinary result data. Allocation and size overflow use OutOfMemoryError.

Method UriComponents.buildOwned

pub effect<'env> fn buildOwned<'text: 'env, 'life1: 'env, 'env>(self: &'life1 UriComponents<'text>) -> silk/result.Result<silk/uri_reference.OwnedUriReference, silk/uri_reference.ParseError> ! OutOfMemoryError ? &mut Allocator

Builds an owned URI reference from every component without copying the completed output.

Details

Nonempty output uses one exact allocation. The completed String is validated and adopted.