silk/uri_percent

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.

Byte percent coding with explicit ownership and caller-controlled storage.

When to use

Use encodeInto and decodeInto to reuse a byte buffer, or encodeToWriter to stream output. Use encodeOwned and decodeOwned when the result needs independent storage.

Details

Encoding creates uppercase escapes and treats every input percent sign as data. Decoding preserves plus signs and arbitrary bytes. Validate UTF-8 separately with String.fromUtf8. Query coding follows generic URI syntax, not HTML form rules.

Import as UriPercent with import silk.uri_percent { UriPercent }.

Public declarations: 4.

PercentComponent

pub enum PercentComponent

The grammar context of raw bytes supplied to percent encoding.

Userinfo

Userinfo = 0

User information; an at sign is escaped and a colon is retained.

RegName

RegName = 1

A registered host name; authority delimiters are escaped.

PathSegment

PathSegment = 2

One path segment; slash is escaped and colon is retained.

FirstPathSegment

FirstPathSegment = 3

The first relative path segment; slash and colon are escaped.

Path

Path = 4

A whole path; slash is retained, but question mark and number sign are escaped.

Unreserved

Unreserved = 5

Only ASCII letters, digits, hyphen, period, underscore, and tilde are retained.

Query

Query = 6

A complete generic query; slash and question mark are retained.

Fragment

Fragment = 7

A complete fragment; slash and question mark are retained.

DecodeError

pub struct DecodeError

The position of a malformed percent escape in the supplied text or bytes.

Field offset

pub offset: usize

The zero-based byte offset of the percent sign that starts the malformed escape.

Decoded

pub union Decoded<'input>

Decoded bytes that borrow unchanged input or own the result of expanding escapes.

Details

The borrowed variant cannot outlive its input. Neither variant guarantees valid UTF-8.

Borrowed

Decoded<'input>.Borrowed { values: &'input [u8] }: Decoded<'input>

Unchanged input without percent signs, requiring no allocation or copy.

Field values

pub values: &'input [u8]

The original byte view, including any literal plus signs.

Owned

Decoded<'input>.Owned { value: Bytes }: Decoded<'input>

Independently owned bytes after percent escapes have been decoded.

Field value

pub value: Bytes

The decoded bytes, which may contain invalid UTF-8.

UriPercent

pub struct UriPercent

The owner of byte percent encoding and decoding operations for URI components.

Associated function UriPercent.encodeOwned

pub effect<'life0> fn encodeOwned<'life0>(values: &'life0 [u8], component: PercentComponent) -> String ! OutOfMemoryError ? &mut Allocator

Encodes raw bytes into independently owned ASCII text with one exact backing allocation.

Details

Empty output does not allocate. Percent signs are always escaped using uppercase hexadecimal. Allocation or size overflow fails with OutOfMemoryError.

Gotchas

Supply raw data, not already escaped text. Whole-path encoding retains slash and colon; use FirstPathSegment for data that must not become a relative reference's scheme.

Associated function UriPercent.encodeInto

pub effect<'env> fn encodeInto<'life0: 'env, 'life1: 'env, 'env>(output: &'life0 mut silk/bytes.Bytes, values: &'life1 [u8], component: PercentComponent) -> () ! OutOfMemoryError ? &mut Allocator

Replaces a reusable byte buffer with percent-encoded ASCII component data.

Details

Computes the size and reserves exact required capacity before changing the contents. Existing sufficient capacity requires no allocation. Failure leaves the original contents intact.

Associated function UriPercent.encodedLength

pub fn encodedLength<'life0>(values: &'life0 [u8], component: PercentComponent) -> silk/option.Option<usize>

Returns the encoded byte count without allocating, or None when the size exceeds usize.

Details

Counts raw data under the selected grammar context, including three bytes for each escape. Use this to reserve a combined serialization before appending its individual components.

Associated function UriPercent.appendEncoded

pub effect<'env> fn appendEncoded<'life0: 'env, 'life1: 'env, 'env>(output: &'life0 mut silk/bytes.Bytes, values: &'life1 [u8], component: PercentComponent) -> () ! OutOfMemoryError ? &mut Allocator

Appends encoded component data while retaining all existing destination bytes.

Details

Computes the additional byte count and reserves exact capacity before mutation. Sufficient capacity requires no allocation. Size overflow or allocation failure leaves the output intact.

Associated function UriPercent.encodeToWriter

pub effect<'life0> fn encodeToWriter<'life0>(values: &'life0 [u8], component: PercentComponent) -> () ! WriterError ? &mut Writer

Streams percent encoding to a Writer without allocating intermediate output storage.

Details

Writes unchanged ASCII runs directly from input and each escape from a three-byte stack array. The Writer provider may allocate independently.

Gotchas

Writer failure may leave partial output. This operation does not flush the provider.

Associated function UriPercent.decodeOwned

pub effect<'life0> fn decodeOwned<'life0>(text: string<'life0>) -> silk/result.Result<silk/bytes.Bytes, silk/uri_percent.DecodeError> ! OutOfMemoryError ? &mut Allocator

Decodes percent escapes into owned arbitrary bytes with one exact backing allocation.

Details

Malformed escapes fail before allocation. Empty output does not allocate. No bytes are zero-filled before being overwritten, and plus signs remain literal bytes.

Associated function UriPercent.decodeInto

pub effect<'env> fn decodeInto<'life0: 'env, 'life1: 'env, 'env>(output: &'life0 mut silk/bytes.Bytes, text: string<'life1>) -> silk/result.Result<(), silk/uri_percent.DecodeError> ! OutOfMemoryError ? &mut Allocator

Replaces reusable byte storage with strictly decoded bytes, preserving literal plus signs.

Details

Validates all escapes and reserves exact capacity before mutation. Malformed input and allocation failure leave existing contents intact. Sufficient capacity requires no allocation.

Associated function UriPercent.decodeInPlace

pub fn decodeInPlace<'life0>(values: &'life0 mut [u8]) -> silk/result.Result<usize, silk/uri_percent.DecodeError>

Strictly decodes a mutable byte slice in place and returns its initialized output-prefix length.

Details

Validates every escape before mutation, so malformed input leaves the slice unchanged. The operation allocates nothing. Output may contain arbitrary bytes, including invalid UTF-8.

Gotchas

Bytes after the returned prefix are unspecified; the slice's physical length does not change.

Associated function UriPercent.decodeOrBorrow

pub effect<'input> fn decodeOrBorrow<'input>(text: string<'input>) -> silk/result.Result<silk/uri_percent.Decoded<'input>, silk/uri_percent.DecodeError> ! OutOfMemoryError ? &mut Allocator

Borrows unchanged input bytes when no percent escapes occur, otherwise returns owned decoded bytes.

Details

The borrowed fast path performs no allocation or copy. Escaped input follows decodeOwned, including strict validation before allocation and preservation of literal plus signs.