WebURL Documentation Beta

Structure Web​URL.​Form​Encoded​Query​Parameters 

@dynamicMemberLookup
public struct FormEncodedQueryParameters

A view of the application/x-www-form-urlencoded key-value pairs in a URL's query.

The formParams view allows you to conveniently get and set the values for particular keys by accessing them as members. For keys which cannot be written as members, the get and set functions provide equivalent functionality. The keys and values will be automatically encoded and decoded.

var url = WebURL("http://example.com/currency/convert?from=EUR&to=USD")!
assert(url.formParams.from == "EUR")

url.formParams.from = "GBP"
assert(url.serialized() == "http://example.com/currency/convert?from=GBP&to=USD")

url.formParams.amount = "20"
assert(url.serialized() == "http://example.com/currency/convert?from=GBP&to=USD&amount=20")

url.formParams.to = "💵"
assert(url.serialized() == "http://example.com/currency/convert?from=GBP&to=%F0%9F%92%B5&amount=20")

Additionally, you can iterate over all of the key-value pairs using the .allKeyValuePairs property:

for (key, value) in url.formParams.allKeyValuePairs {
  // ("from", "GBP")
  // ("to", "💵")
  // ("amount", "20")
}

Key lookup (via .contains, .get, .set, etc) is not Unicode-aware. This means that the Unicode codepoints in the provided key must match exactly with those in the query string after percent-decoding. This matches the behaviour of the URLSearchParams class defined in the URL standard.

In the following example, the character "ñ" is not found when searching using a canonically-equivalent set of codepoints. However, the allKeyValuePairs property provides the key using Swift's built-in String type, which does have Unicode-aware comparison:

let url = WebURL("http://example.com?jalape\u{006E}\u{0303}os=2")!
url.serialized() // "http://example.com/?jalapen%CC%83os=2"
url.formParams.get("jalape\u{006E}\u{0303}os") // "2"
url.formParams.get("jalape\u{00F1}os") // nil
url.formParams.allKeyValuePairs.first(where: { $0.0 == "jalape\u{00F1}os" }) // ("jalapeños", "2")

Also note that modifying any part of the query through this view will re-encode the entire query as application/x-www-form-urlencoded. Again, this matches the behaviour of URLSearchParams in the URL standard.

Member Of

WebURL

A Uniform Resource Locator (URL) is a universal identifier, which often describes the location of a resource.

Nested Types

WebURL.FormEncodedQueryParameters.KeyValuePairs

A Sequence allowing iteration over all form-encoded key-value pairs contained in a URL's query.

Properties

all​Key​Value​Pairs 

public var allKeyValuePairs: KeyValuePairs

A Sequence allowing iteration over all form-encoded key-value pairs contained in this URL's query.

Methods

contains(_:​) 

@inlinable
public func contains<StringType>(_ key: StringType) -> Bool where StringType: StringProtocol

Whether or not the query parameters contain a key-value pair whose key matches the given key.

Note that this lookup is not Unicode-aware: the Unicode codepoints in the given key must match exactly with those in the decoded key-value pair in order to be considered a match.

get(_:​) 

@inlinable
public func get<StringType>(_ key: StringType) -> String? where StringType: StringProtocol

Returns the value from the first key-value pair whose key matches the given key. The returned value is form-decoded.

Note that this lookup is not Unicode-aware: the Unicode codepoints in the given key must match exactly with those in the decoded key-value pair in order to be considered a match.

get​All(_:​) 

@inlinable
public func getAll<StringType>(_ key: StringType) -> [String] where StringType: StringProtocol

Returns the values of all key-value pairs whose key matches the given key. The values are form-decoded.

Note that this lookup is not Unicode-aware: the Unicode codepoints in the given key must match exactly with those in the decoded key-value pair in order to be considered a match.

append(_:​value:​) 

@inlinable
public mutating func append<StringType>(_ key: StringType, value: StringType) where StringType: StringProtocol

Appends the given key-value pair.

The key and value will be form-encoded before they are added to the query. Even if the key is already present, no existing key-value pairs will be removed.

remove(_:​) 

@inlinable
public mutating func remove<StringType>(_ key: StringType) where StringType: StringProtocol

Removes all key-value pairs whose key matches the given key.

Note that this lookup is not Unicode-aware: the Unicode codepoints in the given key must match exactly with those in the decoded key-value pair in order to be considered a match.

remove​All() 

public mutating func removeAll()

Removes all key-value pairs. This is equivalent to setting the URL's query to nil.

set(_:​to:​) 

@inlinable
public mutating func set<StringType>(
  _ key: StringType, to newValue: StringType?
) where StringType: StringProtocol

If key is already present, sets the value of the first key-value pair whose key matches key to newValue. Otherwise, appends key and newValue as a new key-value pair. If newValue is nil, all pairs whose key matches the given key are removed.

The new value (and key, if it is appended) will be form-encoded before it is added to the query. If multiple key-value pairs in the query match key, all other pairs besides the first one will be removed.

Note that this lookup is not Unicode-aware: the Unicode codepoints in the given key must match exactly with those in the decoded key-value pair in order to be considered a match.

append(contents​Of:​) 

@inlinable
public mutating func append<CollectionType, StringType>(
  contentsOf keyValuePairs: CollectionType
) where CollectionType: Collection, CollectionType.Element == (StringType, StringType), StringType: StringProtocol

Appends the given collection of key-value pairs.

The keys and values will be form-encoded before they are added to the query.

append(contents​Of:​) 

@inlinable
public mutating func append<CollectionType, StringType>(
  contentsOf keyValuePairs: CollectionType
)
where
CollectionType: Collection, CollectionType.Element == (key: StringType, value: StringType),
StringType: StringProtocol

Appends the given collection of key-value pairs.

The keys and values will be form-encoded before they are added to the query.

append(contents​Of:​) 

@inlinable
public mutating func append<StringType>(
  contentsOf keyValuePairs: [StringType: StringType]
) where StringType: StringProtocol

Appends the key-value pairs of the given Dictionary.

The keys and values will be form-encoded before they are added to the query.

Operators

+= 

@inlinable
public static func += <CollectionType, StringType>(
  lhs: inout WebURL.FormEncodedQueryParameters, rhs: CollectionType
) where CollectionType: Collection, CollectionType.Element == (StringType, StringType), StringType: StringProtocol

Appends the given collection of key-value pairs.

The keys and values will be form-encoded before they are added to the query.

+= 

@inlinable
public static func += <CollectionType, StringType>(
  lhs: inout WebURL.FormEncodedQueryParameters, rhs: CollectionType
)
where
CollectionType: Collection, CollectionType.Element == (key: StringType, value: StringType),
StringType: StringProtocol

Appends the given collection of key-value pairs.

The keys and values will be form-encoded before they are added to the query.

+= 

@inlinable
public static func += <StringType>(
  lhs: inout WebURL.FormEncodedQueryParameters, rhs: [StringType: StringType]
) where StringType: StringProtocol

Appends the key-value pairs of the given Dictionary.

The keys and values will be form-encoded before they are added to the query.