Structure

URL

A value that identifies the location of a resource, such as an item on a remote server or the path to a local file.

Overview

You can construct URLs and access their parts. For URLs that represent local files, you can also manipulate properties of those files directly, such as changing the file’s last modification date. Finally, you can pass URLs to other APIs to retrieve the contents of those URLs. For example, you can use the URLSession classes to access the contents of remote resources, as described in URL Session Programming Guide.

URLs are the preferred way to refer to local files. Most objects that read data from or write data to a file have methods that accept a URL instead of a pathname as the file reference. For example, you can get the contents of a local file URL as String by calling func init(contentsOf:encoding) throws, or as a Data by calling func init(contentsOf:options) throws.

Topics

Creating a URL from a String

init?(string: String)

Initializes with a string.

init?(string: String, relativeTo: URL?)

Initializes with a string, relative to another URL.

Creating a File URL

init(fileURLWithPath: String)

Initializes a newly created file URL referencing the local file or directory at path.

init(fileURLWithPath: String, isDirectory: Bool)

Initializes a newly created file URL referencing the local file or directory at path.

init(fileURLWithPath: String, isDirectory: Bool, relativeTo: URL?)

Initializes a newly created file URL referencing the local file or directory at path, relative to a base URL.

init(fileURLWithPath: String, relativeTo: URL?)

Initializes a newly created file URL referencing the local file or directory at path, relative to a base URL.

init(fileURLWithFileSystemRepresentation: UnsafePointer<Int8>, isDirectory: Bool, relativeTo: URL?)

Initializes a newly created URL referencing the local file or directory at the file system representation of the path.

Creating a URL by Resolving a Bookmark

init(resolvingAliasFileAt: URL, options: URL.BookmarkResolutionOptions)

Creates and initializes a URL that refers to the location specified by resolving an alias file.

typealias URL.BookmarkResolutionOptions

An alias for bookmark resolution options.

struct NSURL.BookmarkResolutionOptions

Options used when resolving bookmark data.

Working with the Data Representation of a URL

init?(dataRepresentation: Data, relativeTo: URL?, isAbsolute: Bool)

Initializes a newly created URL using the contents of the given data, relative to a base URL.

var dataRepresentation: Data

The data representation of the URL’s relativeString.

Accessing the Parts of a URL

var absoluteString: String

The absolute string for the URL.

var absoluteURL: URL

The absolute URL.

var baseURL: URL?

The base URL.

var fragment: String?

The fragment component of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

var host: String?

The host component of a URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

var lastPathComponent: String

The last path component of the URL, or an empty string if the path is an empty string.

var path: String

The path component of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise an empty string.

var pathComponents: [String]

The path components of the URL, or an empty array if the path is an empty string.

var pathExtension: String

The path extension of the URL, or an empty string if the path is an empty string.

var port: Int?

The port component of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

var query: String?

The query of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

var relativePath: String

The relative path of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

var relativeString: String

The relative portion of a URL.

var scheme: String?

The scheme of the URL.

var standardized: URL

A version of the URL with any instances of “..” or “.” removed from its path.

var standardizedFileURL: URL

A standardized version of the path of a file URL.

var user: String?

The user component of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

var password: String?

The password component of the URL if the URL conforms to RFC 1808 (the most common form of URL), otherwise nil.

Accessing Resource Values

func resourceValues(forKeys: Set<URLResourceKey>)

Return a collection of resource values identified by the given resource keys.

func setResourceValues(URLResourceValues)

Sets the resource value identified by a given resource key.

func removeCachedResourceValue(forKey: URLResourceKey)

Removes the cached resource value identified by a given resource value key from the URL object.

func removeAllCachedResourceValues()

Removes all cached resource values and all temporary resource values from the URL object.

func setTemporaryResourceValue(Any, forKey: URLResourceKey)

Sets a temporary resource value on the URL object.

struct URLResourceKey

Keys that apply to file system URLs.

struct URLResourceValues

The properties supported by file system resources.

Working with File URLs

var isFileURL: Bool

A Boolean that is true if the scheme is file:.

var hasDirectoryPath: Bool

A Boolean that is true if the URL path represents a directory.

func withUnsafeFileSystemRepresentation<ResultType>((UnsafePointer<Int8>?) -> ResultType)

Passes the URL’s path in file system representation to a block.

func resolveSymlinksInPath()

Resolves any symlinks in the path of a file URL.

func resolvingSymlinksInPath()

Resolves any symlinks in the path of a file URL.

func standardize()

Standardizes the path of a file URL.

Adding Path Components

func appendPathComponent(String)

Appends a path component to the URL.

func appendPathComponent(String, isDirectory: Bool)

Appends a path component to the URL.

func appendingPathComponent(String)

Returns a URL constructed by appending the given path component to self.

func appendingPathComponent(String, isDirectory: Bool)

Returns a URL constructed by appending the given path component to self.

Adding a Path Extension

func appendPathExtension(String)

Appends the given path extension to self.

func appendingPathExtension(String)

Returns a URL constructed by appending the given path extension to self.

Removing Path Components

func deleteLastPathComponent()

Returns a URL constructed by removing the last path component of self.

func deletingLastPathComponent()

Returns a URL constructed by removing the last path component of self.

Removing a Path Extension

func deletePathExtension()

Returns a URL constructed by removing any path extension.

func deletingPathExtension()

Returns a URL constructed by removing any path extension.

Creating Bookmarks

func bookmarkData(options: URL.BookmarkCreationOptions, includingResourceValuesForKeys: Set<URLResourceKey>?, relativeTo: URL?)

Returns bookmark data for the URL, created with specified options and resource values.

static func bookmarkData(withContentsOf: URL)

Initializes and returns bookmark data derived from an alias file pointed to by a specified URL.

static func writeBookmarkData(Data, to: URL)

Creates an alias file on disk at a specified location with specified bookmark data.

static func resourceValues(forKeys: Set<URLResourceKey>, fromBookmarkData: Data)

Returns the resource values for properties identified by a specified array of keys contained in specified bookmark data.

typealias URL.BookmarkCreationOptions

An alias for bookmark creation options.

struct NSURL.BookmarkCreationOptions

Options used when creating bookmark data.

Checking Reachability

func checkResourceIsReachable()

Returns whether the URL’s resource exists and is reachable.

Working with Promised Items

func checkPromisedItemIsReachable()

Returns whether the promised item URL’s resource exists and is reachable.

func promisedItemResourceValues(forKeys: Set<URLResourceKey>)

Gets resource values from URLs of ‘promised’ items.

Working with Security Scoped Resources

func startAccessingSecurityScopedResource()

Given a url created by resolving a bookmark data created with security scope, make the resource referenced by the url accessible to the process.

func stopAccessingSecurityScopedResource()

Revokes the access granted to the url by a prior successful call to the complementary start function.

Comparing URLs

static func !=(URL, URL)

Returns a Boolean value indicating whether two values are not equal.

static func ==(URL, URL)

Indicates whether two URLs are the same.

Describing a URL

var description: String

A textual description of the URL.

var debugDescription: String

A textual description of the URL suitable for debugging.

var customPlaygroundQuickLook: PlaygroundQuickLook

A playground quicklook for the URL.

var hashValue: Int

The computed hash value for the URL.

Using Reference Types

class NSURL

An object representing the location of a resource that bridges to URL; use NSURL when you need reference semantics or other Foundation-specific behavior.

typealias URL.ReferenceType

An alias for this value type's equivalent reference type.

See Also

URLs

struct URLComponents

A structure that parses URLs into and constructs URLs from their constituent parts.

struct URLQueryItem

A single name-value pair from the query portion of a URL.