Percent-encoding v0.1.0

Percent-encoding bytes for URLs, with the set of characters left as they are.

`PercentSet`

pub enum PercentSet {
    Component,
    Path,
    Form
}

Which characters percent-encoding leaves as they are. Copy, carrying no payload. Every set leaves the unreserved characters of RFC 3986 alone, apart from Form, which escapes ~ as HTML requires.

Source

Cases

Name	Description
`Component`	Only the unreserved characters: letters, digits, `-`, `.`, `_` and `~`. Right for a single query name or value, a single path segment, or any value placed between delimiters, since every delimiter is escaped.
`Path`	The unreserved characters, the sub-delimiters `!$&'()*+,;=`, and `:`, `@` and `/`. Right for a whole path that is already split into segments the way it should be.
`Form`	The `application/x-www-form-urlencoded` serialization: letters, digits, `*`, `-`, `.` and `_` stay, a space becomes `+`, and everything else is escaped. Decoding in this set reads `+` as a space.

`PercentEncodedLength`

pub func PercentEncodedLength(
    bytes: byte[..],
    set: PercentSet
) -> uint

pub func PercentEncodedLength(
    text: char8[..],
    set: PercentSet
) -> uint

How many characters the percent-encoded form of bytes occupies in set. Exact rather than a bound: one character for each byte the set leaves alone, or for a space in the form set, and three for every other byte. Runs in time linear in the length and allocates nothing.

Overload	Summary
`pub func PercentEncodedLength(bytes: byte[..], set: PercentSet) -> uint`	How many characters the percent-encoded form of `bytes` occupies in `set`.
`pub func PercentEncodedLength(text: char8[..], set: PercentSet) -> uint`	How many characters the percent-encoded form of the bytes of `text` occupies in `set`.

Source

Parameters

Name	Type	Description
`bytes`	`byte[..]`	the bytes to encode
`set`	`PercentSet`	which characters stay as they are
`text`	`char8[..]`	the text whose bytes to encode

Returns: the number of characters PercentEncode writes

`PercentEncode`

pub func PercentEncode(
    bytes: byte[..],
    into: var char8[..],
    set: PercentSet
) -> uint ! FormatError

pub func PercentEncode(
    text: char8[..],
    into: var char8[..],
    set: PercentSet
) -> uint ! FormatError

Writes the bytes of text percent-encoded for set into into. The byte form, reached without the caller reinterpreting the text first: each UTF-8 code unit is one byte, so a character outside ASCII becomes one escape per byte of its UTF-8 form, as URIs require. The failure the byte form reports, with the same guarantee.

Overload	Summary
`pub func PercentEncode(bytes: byte[..], into: var char8[..], set: PercentSet) -> uint ! FormatError`	Writes `bytes` percent-encoded for `set` into `into`.
`pub func PercentEncode(text: char8[..], into: var char8[..], set: PercentSet) -> uint ! FormatError`	Writes the bytes of `text` percent-encoded for `set` into `into`.

Source

Parameters

Name	Type	Description
`bytes`	`byte[..]`	the bytes to encode
`into`	`var char8[..]`	the destination, at least `PercentEncodedLength(bytes, set)` characters
`set`	`PercentSet`	which characters stay as they are
`text`	`char8[..]`	the text whose bytes to encode

Returns: the number of characters written

`PercentDecodedLength`

pub func PercentDecodedLength(text: char8[..]) -> uint ! DecodeError

How many bytes percent-encoded text decodes to, after checking that every escape is well formed. Each % followed by two hexadecimal digits of either case counts as one byte, and every other character as one. Reports InvalidEscape at the first % that is not followed by two hexadecimal digits. Runs in time linear in the length and allocates nothing.

Source

Parameters

Name	Type	Description
`text`	`char8[..]`	the percent-encoded text

Returns: the number of bytes PercentDecode writes for it

`PercentDecode`

pub func PercentDecode(
    text: char8[..],
    into: var byte[..],
    set: PercentSet
) -> uint ! DecodeError

Reads percent-encoded text into into, turning each escape back into its byte. Characters outside an escape are copied as they are, except that + becomes a space when set is Form; the other sets give + no special meaning. Reports InvalidEscape at the first % that is not followed by two hexadecimal digits, and InsufficientCapacity with the length needed when into is too short; both leave into untouched, because the whole text is checked before anything is written.

Source

Parameters

Name	Type	Description
`text`	`char8[..]`	the percent-encoded text to decode
`into`	`var byte[..]`	the destination, at least `PercentDecodedLength(text)` bytes
`set`	`PercentSet`	the set the text was encoded for, which decides how `+` is read

Returns: the number of bytes written

Hexadecimal

Bytes as hexadecimal digits in either case, and a view that prints them.

Overview

URLs: parsing, normalizing and resolving them, and reading and building their queries

Edit this page on GitHub