URLTemplate

URLTemplate

A URL that may contain variable placeholders.

public struct URLTemplate: Hashable, RawRepresentable 

Variable placeholders are enclosed with curly braces. They can exist anywhere within the URL.

Examples:

// no variables
"https://website.com/a/path?query=value"

// scheme
"{scheme}://website.com/a/path?query=value"

// host
"https://{host}/a/path?query=value"

// just the domain
"https://{domain}.com/a/path?query=value"

// the whole url
"{server}"

// etc.

A URLTemplate that does not contain any variables can be turned into a Foundation URL (assuming it is an otherwise valid URL) which you can access with the url property.

A URLTemplate that contains variables can be turned into a template with no variables (and subsequently a Foundation URL) with the replacing(_:) function that takes a dictionary of variable values to insert into the template. You can also choose to only replace some of the variables this way.

Inheritance

Decodable, Encodable, Hashable, RawRepresentable

Initializers

init?(rawValue:)

Create a URLTemplate from the string if possible.

public init?(rawValue: String) 

A non-throwing version of init(templateString:).

init(templateString:)

Create a URLTemplate from the string if possible.

public init(templateString: String) throws 

A throwing version of init?(rawValue:).

init(url:)

Create a constant (no variables) URLTemplate from the given URL.

public init(url: URL) 

init(reducingComponents:)

Construct a URL template from the given components. Neighboring .constant components in the array will be combined.

public init(reducingComponents components: [Component]) 

init(from:)

public init(from decoder: Decoder) throws 

Properties

rawValue

The string value of the URL.

public let rawValue: String

This is equivalent to the absoluteString (i.e. the entire URL).

components

The variable and constant components of teh URL.

public let components: [Component]

Variables are enclosed in curly braces ({variable}) and everything between variables is "constant."

In the URL {scheme}://website.com/{path} there are two variables (scheme and path) separated by the "://website.com/" portion which is a constant.

absoluteString

The entire URL as a string.

public var absoluteString: String 

This is equivalent to the absoluteString provided by the Foundation URL type except that a URLTemplate's absoluteString can contain variable placeholders.

url

Get a URL from this templated URL if it is a valid URL already.

public var url: URL? 

Templated URLs with variables in them will not be valid URLs and are therefore guaranteed to return nil.

variables

Get the names of all variables in the URL Template.

public var variables: [String] 

Methods

replacing(_:)

For all variables in this template that have keys in the given dictionary, replace the variable with the value under the given key.

public func replacing(_ variableDictionary: [String : String]) -> URLTemplate 

This results in a new URLTemplate with a constant value in place of all variables that were replaced. The URLTemplate gets reformed, so any constants formed by such a replacement that neighbor other constants become one constant (there will never be two constants next to each other, even after variable replacement occurs).

If you have replaced all variables in the template, you can attempt to create a well-formed Foundation URL by accessing the url property of the resulting URLTemplate.

Example

"{scheme}://{website}.com/{path}"
[
    .variable(name: "scheme"),
    .constant("://"),
    .variable(name: "website"),
    .constant(".com/")
    .variable(name: "path")
]

-> replacing(["scheme": "https", "path": "welcome"])

"https://{website}.com/welcome"
[
    .constant("https://"),
    .variable(name: "website"),
    .constant(".com/welcome")
]

If you want to create a valid URL from the template, all variables must be replaced. Picking up with the above example, we could replace the last variable and then request the URLTemplate url property.

Example

    -> replacing(["website": "mysite"])

    "https://mysite.com/welcome"
    [
        .constant("https://mysite.com/welcome")
    ]

encode(to:)

public func encode(to encoder: Encoder) throws