Contents

URL.FormatStyle

A structure that converts between URL instances and their textual representations.

Declaration

struct FormatStyle

Overview

Instances of URL.FormatStyle create localized, human-readable text from URL instances and parse string representations of URLs into instances of URL.

Formatting URLs

Use the formatted() method to create a string representation of a URL using the default URL.FormatStyle configuration. As seen in the following example, the default style creates a string with the scheme, host, and path, but not the port or query.

let url = URL(string:"https://www.example.com:8080/path/to/endpoint?key=value")!
let formatted = url.formatted() // "https://www.example.com/path/to/endpoint"

You can specify a format style by providing an argument to the format(_:) method. The following example uses the previous URL, but preserves only the host and path.

let url = URL(string:"https://www.example.com:8080/path/to/endpoint?key=value")!
let style = URL.FormatStyle(scheme: .never,
                            user: .never,
                            password: .never,
                            host: .always,
                            port: .never,
                            path: .always,
                            query: .never,
                            fragment: .never)
let formatted = style.format(url) // "www.example.com/path/to/endpoint"

Instantiate a style when you want to format multiple URL instances with the same style. For one-time access to a default style, you can use the static accessor url at call points that expect the URL.FormatStyle type, such as the format(_:) method. This means you can write the example above as follows:

let url = URL(string:"https://www.example.com:8080/path/to/endpoint?key=value")!
let formatted = url.formatted(.url
    .scheme(.never)
    .host(.always)
    .port(.never)
    .path(.always)
    .query(.never)) // "www.example.com/path/to/endpoint"

This example works by taking the default style provided by url, then customizing it with calls to the style modifiers in Customizing style behavior.

Parsing URLs

You can use URL.FormatStyle to parse strings into URL values. To do this, create a URL.ParseStrategy from a format style, then call the strategy’s parse(_:) method.

let style = URL.FormatStyle(scheme: .always,
                            user: .never,
                            password: .never,
                            host: .always,
                            port: .always,
                            path: .always,
                            query: .always,
                            fragment: .never)
let urlString = "https://www.example.com:8080/path/to/endpoint?key=value"
let url = try? style.parseStrategy.parse(urlString)

Matching regular expressions

Along with parsing URL values in strings, you can use the regular expression domain-specific language provided by Swift to match and capture URL substrings. The following example scans source input that’s expected to contain a timestamp, some whitespace, and a URL.

import RegexBuilder
let source = "7/31/2022, 5:15:12 AM  https://www.example.com/productList?query=slushie"
let matcher = Regex {
    One(.dateTime(date: .numeric,
                  time: .standard,
                  locale: Locale(identifier: "en_US"),
                  timeZone: TimeZone(identifier: "PST")!))
    OneOrMore(.horizontalWhitespace)
    Capture {
        One(.url(scheme: .required,
                 user: .optional,
                 password: .optional,
                 host: .required,
                 port: .defaultValue(8088),
                 path: .optional,
                 query: .optional,
                 fragment: .optional))
    }
}
guard let match = source.firstMatch(of: matcher) else { return }
let url = match.1 // url = https://www.example.com:8088/productList?query=slushie

Topics

Creating a URL format style

Customizing style behavior

Parsing URLs

Enumerations

See Also

Data formatting in Swift