silk.url.percent.

When to use#

Use UrlPercent to build a component of a URL for a browser-compatible URL, or to read application/x-www-form-urlencoded text. For RFC 3986 URIs, use silk.uri.percent.

Details#

Encoding works on UTF-8 bytes. Each byte that is in the selected UrlEncodeSet becomes %XX with uppercase hexadecimal digits; bytes 0x80 and above are in every set. Decoding is lenient, as the URL Standard specifies: a % that does not start a valid escape stays as it is.

Examples#

Encode a query value#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.collections.bytes { Bytes }
import silk.text.string { String }
import silk.url.percent { UrlEncodeSet, UrlPercent }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut output = Bytes.make()
  run UrlPercent.appendEncoded(&mut output, String.utf8Bytes("a b&c"), UrlEncodeSet.Component)
    |> Effect.provideMut<Allocator>(&mut allocator)
  if Bytes.asSlice(&output) != b"a%20b%26c" {
    return 1
  }
  return 0
}

Import as UrlPercent with import silk.url.percent { UrlPercent }.

Public declarations: 2.

UrlEncodeSet#

pub enum UrlEncodeSet

A percent-encode set of the URL Standard. Each set holds the bytes that become %XX.

Details#

Every set holds the C0 controls (0x00 to 0x1F) and the bytes 0x7F and above. Each set after C0Control holds the bytes of the set before it, except FormUrlencoded, which holds those of Component.

C0Control#

C0Control

The C0 control percent-encode set: only the C0 controls and 0x7F and above.

Fragment#

Fragment

The fragment set: adds space, ", <, >, and `.

Query#

Query

The query set: adds space, ", #, <, and > to C0Control.

SpecialQuery#

SpecialQuery

The special-query set, for the query of a special URL: adds ' to Query.

Path#

Path

The path set: adds ?, ^, `, {, and } to Query.

Userinfo#

Userinfo

The userinfo set: adds /, :, ;, =, @, [ to ^, and | to Path.

Component#

Component

The component set: adds $, %, &, +, and , to Userinfo. It encodes %.

FormUrlencoded#

FormUrlencoded

The application/x-www-form-urlencoded set: adds !, ' to ), and ~ to Component. Space is encoded as + when the caller asks for it.

UrlPercent#

pub struct UrlPercent

Functions that percent-encode and percent-decode with the URL Standard's rules.

Implementation UrlPercent#

impl UrlPercent

Associated function encodes#

pub fn encodes(value: u8, set: UrlEncodeSet) -> bool

Returns whether value is in set, so that encoding writes it as %XX.

Associated function appendEncoded#

pub effect fn appendEncoded(output: &mut Bytes, values: &[u8], set: UrlEncodeSet) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends values encoded with set to output.

Details#

A % in values stays as it is in every set except Component and FormUrlencoded, so text that is already encoded does not change in the other sets.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function appendFormEncoded#

pub effect fn appendFormEncoded(output: &mut Bytes, values: &[u8], set: UrlEncodeSet) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends values encoded with set to output, and writes each space as +.

Details#

It is the application/x-www-form-urlencoded serializer's encoding of a name or a value when set is FormUrlencoded.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function appendDecoded#

pub effect fn appendDecoded(output: &mut Bytes, values: &[u8], plusIsSpace: bool) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends the bytes of values with each valid %XX escape decoded to output.

Details#

A % that is not followed by two hexadecimal digits stays as it is. When plusIsSpace is true, each + becomes a space first, as form decoding does. The result is not always valid UTF-8.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function appendDecodedText#

pub effect fn appendDecodedText(output: &mut String, values: &[u8], plusIsSpace: bool) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends the text of values to output: the percent-decoded bytes, read as UTF-8.

Details#

It is the URL Standard's percent-decode followed by UTF-8 decode without BOM. Each invalid UTF-8 sequence becomes U+FFFD, and a leading byte order mark stays. When plusIsSpace is true, each + becomes a space first, as form decoding does.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function appendUtf8Lossy#

pub effect fn appendUtf8Lossy(output: &mut String, values: &[u8]) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends values read as UTF-8 to output, with each invalid sequence replaced by U+FFFD.

Details#

It is the Encoding Standard's UTF-8 decode without BOM: a maximal invalid subpart becomes one U+FFFD, and a leading byte order mark stays.

Errors#

• OutOfMemoryError if the Allocator fails.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.