WebURL Documentation Beta

Protocol Percent​Encode​Set 

public protocol PercentEncodeSet

A set of ASCII code-points which should be percent-encoded.

Percent-encoding transforms arbitrary bytes to ASCII strings (e.g. the byte value 200, or 0xC8, to the string "%C8"), and is most commonly used to escape special characters in URLs. Bytes within the ASCII range are encoded according to the encode-set's shouldPercentEncode(ascii:) method, and bytes which are not ASCII code-points are always percent-encoded.

The following example demonstrates an encode-set which encodes ASCII single and double quotation marks:

struct NoQuotes: PercentEncodeSet {
  func shouldPercentEncode(ascii codePoint: UInt8) -> Bool {
    codePoint == Character("\"").asciiValue! ||
    codePoint == Character("'").asciiValue!
  }
}

#"Quoth the Raven "Nevermore.""#.percentEncoded(using: NoQuotes()) // "Quoth the Raven %22Nevermore.%22"

Form-encoding is a legacy variant of percent-encoding, including a SubstitutionMap which replaces spaces with the "+" character. Whilst you may define your own encode-sets with custom substitution maps, doing so is often unwise.

Default Implementations

substitutions 

@inlinable @inline(__always)
public var substitutions: NoSubstitutions

c0Control​Set 

@inlinable
public static var c0ControlSet: URLEncodeSet.C0Control

The C0 control percent-encode set.

fragment​Set 

@inlinable
public static var fragmentSet: URLEncodeSet.Fragment

The fragment percent-encode set.

query​Set 

@inlinable
public static var querySet: URLEncodeSet.Query

The query percent-encode set.

special​Query​Set 

@inlinable
public static var specialQuerySet: URLEncodeSet.SpecialQuery

The special query percent-encode set.

path​Set 

@inlinable
public static var pathSet: URLEncodeSet.Path

The path percent-encode set.

user​Info​Set 

@inlinable
public static var userInfoSet: URLEncodeSet.UserInfo

The userinfo percent-encode set.

url​Component​Set 

@inlinable
public static var urlComponentSet: URLEncodeSet.Component

The component percent-encode set.

form​Encoding 

@inlinable
public static var formEncoding: URLEncodeSet.FormEncoding

The application/x-www-form-urlencoded percent-encode set.

Requirements

should​Percent​Encode(ascii:​) 

func shouldPercentEncode(ascii codePoint: UInt8) -> Bool

Whether or not the given ASCII codePoint should be percent-encoded.

Parameters

code​Point UInt8

An ASCII code-point. Always in the range 0...127.

Returns

Whether or not codePoint should be percent-encoded.

Substitutions 

associatedtype Substitutions: SubstitutionMap = NoSubstitutions

A SubstitutionMap which may replace ASCII code-points that are not percent-encoded.

This is a legacy feature to support form-encoding; modern percent-encoding does not use substitutions. Should you have reason to create a custom substitution map, please observe the following guidelines:

  1. The set of code-points to percent-encode and substitute must not overlap. There must be no code-point x for which substitutions.substitute(ascii: x) != nil and shouldPercentEncode(ascii: x) == true.

  2. Substitute code-points returned by substitute(ascii:) should be percent-encoded. In other words, if y = substitutions.substitute(ascii: x), shouldPercentEncode(ascii: y) should be true.

For example, form-encoding substitutes spaces with the "+" character. It would be incorrect for that encode-set to say that the space character should be both substituted and percent-encoded (#1 above), and it must ensure that actual "+" characters in the source data are percent-encoded, so all "+" characters in the result can be interpreted as encoded spaces (#2 above).

substitutions 

var substitutions: Substitutions

The substitution map which applies to ASCII code-points that are not percent-encoded.