System · IOS API REFERENCE

FilePath

struct · iOS 14.0+ · SDK 27.1

struct FilePath

Represents a location in the file system. This structure recognizes directory separators (e.g. `/`), roots, and requires that the content terminates in a NUL (`0x0`). Beyond that, it does not give any meaning to the bytes that it contains. The file system defines how the content is interpreted; for example, by its choice of string encoding. On construction, `FilePath` will normalize separators by removing redundant intermediary separators and stripping any trailing separators. On Windows, `FilePath` will also normalize forward slashes `/` into backslashes `\`, as preferred by the platform. The code below creates a file path from a string literal, and then uses it to open and append to a log file: let message: String = "This is a log message." let path: FilePath = "/tmp/log" let fd = try FileDescriptor.open(path, .writeOnly, options: .append) try fd.closeAfter { try fd.writeAll(message.utf8) } File paths conform to the <doc://com.apple.documentation/documentation/swift/equatable> and <doc://com.apple.documentation/documentation/swift/hashable> protocols by performing the protocols' operations on their raw byte contents. This conformance allows file paths to be used, for example, as keys in a dictionary. However, the rules for path equivalence are file-system–specific and have additional considerations like case insensitivity, Unicode normalization, and symbolic links.

Members (53)

get · iOS 15.0+

components

TypeScript

get components(): FilePath_ComponentView

Swift declaration

var components: FilePath.ComponentView { get set }

View the non-root components that make up this path.

set · iOS 15.0+

components

TypeScript

set components(value: FilePath_ComponentView)

Swift declaration

var components: FilePath.ComponentView { get set }

View the non-root components that make up this path.

get · iOS 15.0+

isAbsolute

TypeScript

get isAbsolute(): boolean

Swift declaration

var isAbsolute: Bool { get }

Returns true if this path uniquely identifies the location of a file without reference to an additional starting location. On Unix platforms, absolute paths begin with a `/`. `isAbsolute` is equivalent to `root != nil`. On Windows, absolute paths are fully qualified paths. `isAbsolute` is _not_ equivalent to `root != nil` for traditional DOS paths (e.g. `C:foo` and `\bar` have roots but are not absolute). UNC paths and device paths are always absolute. Traditional DOS paths are absolute only if they begin with a volume or drive followed by a `:` and a separator. NOTE: This does not perform shell expansion or substitute environment variables; paths beginning with `~` are considered relative. Examples: * Unix: * `/usr/local/bin` * `/tmp/foo.txt` * `/` * Windows: * `C:\Users\` * `\\?\UNC\server\share\bar.exe` * `\\server\share\bar.exe`

get · iOS 15.0+

isRelative

TypeScript

get isRelative(): boolean

Swift declaration

var isRelative: Bool { get }

Returns true if this path is not absolute (see `isAbsolute`). Examples: * Unix: * `~/bar` * `tmp/foo.txt` * Windows: * `bar\baz` * `C:Users\` * `\Users`

get · iOS 14.0+

description

TypeScript

get description(): string

Swift declaration

var description: String { get }

A textual representation of the file path. If the content of the path isn't a well-formed Unicode string, this replaces invalid bytes with U+FFFD. See `String.init(decoding:)`

method · iOS 14.0+

withCString

TypeScript

withCString(body: ((arg0: SDKHandle) => unknown)): unknown

Swift declaration

func withCString<Result>(_ body: (UnsafePointer<CChar>) throws -> Result) rethrows -> Result

For backwards compatibility only. This function is equivalent to the preferred `withPlatformString`.

method · iOS 15.0+

removePrefix

TypeScript

removePrefix(prefix: FilePath): boolean

Swift declaration

mutating func removePrefix(_ prefix: FilePath) -> Bool

If `prefix` is a prefix of `self`, removes it and returns `true`. Otherwise returns `false`. Example: var path: FilePath = "/usr/local/bin" path.removePrefix("/usr/bin") // false path.removePrefix("/us") // false path.removePrefix("/usr/local") // true, path is "bin"

method · iOS 15.0+

removingRoot

TypeScript

removingRoot(): FilePath

Swift declaration

func removingRoot() -> FilePath

Creates a new path containing just the components, i.e. everything after `root`. Returns self if `root == nil`. Examples: * Unix: * `/foo/bar => foo/bar` * `foo/bar => foo/bar` * `/ => ""` * Windows: * `C:\foo\bar => foo\bar` * `foo\bar => foo\bar` * `\\?\UNC\server\share\file => file` * `\\?\device\folder\file.exe => folder\file.exe` * `\\server\share\file => file` * `\ => ""`

get · iOS 15.0+

lastComponent

TypeScript

get lastComponent(): (FilePath_Component) | null

Swift declaration

var lastComponent: FilePath.Component? { get }

Returns the final component of the path. Returns `nil` if the path is empty or only contains a root. Note: Even if the final component is a special directory (`.` or `..`), it will still be returned. See `lexicallyNormalize()`. Examples: * Unix: * `/usr/local/bin/ => bin` * `/tmp/foo.txt => foo.txt` * `/tmp/foo.txt/.. => ..` * `/tmp/foo.txt/. => .` * `/ => nil` * Windows: * `C:\Users\ => Users` * `C:Users\ => Users` * `C:\ => nil` * `\Users\ => Users` * `\\?\UNC\server\share\bar.exe => bar.exe` * `\\server\share => nil` * `\\?\UNC\server\share\ => nil`

init · iOS 14.0+

init

TypeScript

static initStringLiteral(stringLiteral: string): FilePath

Swift declaration

init(stringLiteral: String)

Creates a file path from a string literal. - Parameter stringLiteral: A string literal whose Unicode encoded contents to use as the contents of the path.

init · iOS 15.0+

init

TypeScript

static initPlatformString(platformString: SDKHandle): FilePath

Swift declaration

init(platformString: UnsafePointer<CInterop.PlatformChar>)

Creates a file path by copying bytes from a null-terminated platform string. - Parameter platformString: A pointer to a null-terminated platform string.

init · iOS 15.0+

init

TypeScript

static initPlatformString11582(platformString: string): FilePath

Swift declaration

init(platformString: String)

init · iOS 15.0+

init

TypeScript

static initPlatformString17098(platformString: Array<number>): FilePath

Swift declaration

init(platformString: [CInterop.PlatformChar])

Creates a file path by copying bytes from a null-terminated platform string. - Note It is a precondition that `platformString` must be null-terminated. The absence of a null byte will trigger a runtime error. - Parameter platformString: A null-terminated platform string.

init · iOS 15.0+

init

TypeScript

static initPlatformString31620(platformString: number): { $ret: FilePath; $out: { "platformString": number } }

Swift declaration

init(platformString: inout CInterop.PlatformChar)

Omit the output parameters from the call. The result contains $ret and $out, with platformString inside $out.

method · iOS 15.0+

reserveCapacity

TypeScript

reserveCapacity(minimumCapacity: number): void

Swift declaration

mutating func reserveCapacity(_ minimumCapacity: Int)

Reserve enough storage space to store `minimumCapacity` platform characters.

get · iOS 14.0+

debugDescription

TypeScript

get debugDescription(): string

Swift declaration

var debugDescription: String { get }

A textual representation of the file path, suitable for debugging. If the content of the path isn't a well-formed Unicode string, this replaces invalid bytes with U+FFFD. See `String.init(decoding:)`

get · iOS 15.0+

isLexicallyNormal

TypeScript

get isLexicallyNormal(): boolean

Swift declaration

var isLexicallyNormal: Bool { get }

Whether the path is in lexical-normal form, that is `.` and `..` components have been collapsed lexically (i.e. without following symlinks). Examples: * `"/usr/local/bin".isLexicallyNormal == true` * `"../local/bin".isLexicallyNormal == true` * `"local/bin/..".isLexicallyNormal == false`

method · iOS 15.0+

lexicallyNormalize

TypeScript

lexicallyNormalize(): void

Swift declaration

mutating func lexicallyNormalize()

Collapse `.` and `..` components lexically (i.e. without following symlinks). Examples: * `/usr/./local/bin/.. => /usr/local` * `/../usr/local/bin => /usr/local/bin` * `../usr/local/../bin => ../usr/bin`

method · iOS 15.0+

lexicallyResolving

TypeScript

lexicallyResolving(subpath: FilePath): (FilePath) | null

Swift declaration

func lexicallyResolving(_ subpath: FilePath) -> FilePath?

Create a new `FilePath` by resolving `subpath` relative to `self`, ensuring that the result is lexically contained within `self`. `subpath` will be lexically normalized (see `lexicallyNormalize`) as part of resolution, meaning any contained `.` and `..` components will be collapsed without resolving symlinks. Any root in `subpath` will be ignored. Returns `nil` if the result would "escape" from `self` through use of the special directory component `..`. This is useful for protecting against arbitrary path traversal from an untrusted subpath: the result is guaranteed to be lexically contained within `self`. Since this operation does not consult the file system to resolve symlinks, any escaping symlinks nested inside of `self` can still be targeted by the result. Example: let staticContent: FilePath = "/var/www/my-website/static" let links: [FilePath] = ["index.html", "/assets/main.css", "../../../../etc/passwd"] links.map { staticContent.lexicallyResolving($0) } // ["/var/www/my-website/static/index.html", // "/var/www/my-website/static/assets/main.css", // nil]

method · iOS 15.0+

withPlatformString

TypeScript

withPlatformString(body: ((arg0: SDKHandle) => unknown)): unknown

Swift declaration

func withPlatformString<Result>(_ body: (UnsafePointer<CInterop.PlatformChar>) throws -> Result) rethrows -> Result

Calls the given closure with a pointer to the contents of the file path, represented as a null-terminated platform string. - Parameter body: A closure with a pointer parameter that points to a null-terminated platform string. If `body` has a return value, that value is also used as the return value for this method. - Returns: The return value, if any, of the `body` closure parameter. The pointer passed as an argument to `body` is valid only during the execution of this method. Don't try to store the pointer for later use.

method · iOS 15.0+

lexicallyNormalized

TypeScript

lexicallyNormalized(): FilePath

Swift declaration

func lexicallyNormalized() -> FilePath

Returns a copy of `self` in lexical-normal form, that is `.` and `..` components have been collapsed lexically (i.e. without following symlinks). See `lexicallyNormalize`

method · iOS 15.0+

removeLastComponent

TypeScript

removeLastComponent(): boolean

Swift declaration

@discardableResult mutating func removeLastComponent() -> Bool

In-place mutating variant of `removingLastComponent`. If `self` only contains a root, does nothing and returns `false`. Otherwise removes `lastComponent` and returns `true`. Example: var path = "/usr/bin" path.removeLastComponent() == true // path is "/usr" path.removeLastComponent() == true // path is "/" path.removeLastComponent() == false // path is "/"

method · iOS 15.0+

removingLastComponent

TypeScript

removingLastComponent(): FilePath

Swift declaration

func removingLastComponent() -> FilePath

Creates a new path with everything up to but not including `lastComponent`. If the path only contains a root, returns `self`. If the path has no root and only includes a single component, returns an empty FilePath. Examples: * Unix: * `/usr/bin/ls => /usr/bin` * `/foo => /` * `/ => /` * `foo => ""` * Windows: * `C:\foo\bar.exe => C:\foo` * `C:\ => C:\` * `\\server\share\folder\file.txt => \\server\share\folder` * `\\server\share\ => \\server\share\`

method · iOS 15.0+

ends

TypeScript

ends(other: FilePath): boolean

Swift declaration

func ends(with other: FilePath) -> Bool

Returns whether `other` is a suffix of `self`, only considering whole path components. Example: let path: FilePath = "/usr/bin/ls" path.ends(with: "ls") // true path.ends(with: "bin/ls") // true path.ends(with: "usr/bin/ls") // true path.ends(with: "/usr/bin/ls///") // true path.ends(with: "/ls") // false

method · iOS 15.0+

push

TypeScript

push(other: FilePath): void

Swift declaration

mutating func push(_ other: FilePath)

If `other` does not have a root, append each component of `other`. If `other` has a root, replaces `self` with other. This operation mimics traversing a directory structure (similar to the `cd` command), where pushing a relative path will append its components and pushing an absolute path will first clear `self`'s existing components. Example: var path: FilePath = "/tmp" path.push("dir/file.txt") // path is "/tmp/dir/file.txt" path.push("/bin") // path is "/bin"

get · iOS 15.0+

root

TypeScript

get root(): (FilePath_Root) | null

Swift declaration

var root: FilePath.Root? { get set }

Returns the root of a path if there is one, otherwise `nil`. On Unix, this will return the leading `/` if the path is absolute and `nil` if the path is relative. On Windows, for traditional DOS paths, this will return the path prefix up to and including a root directory or a supplied drive or volume. Otherwise, if the path is relative to both the current directory and current drive, returns `nil`. On Windows, for UNC or device paths, this will return the path prefix up to and including the host and share for UNC paths or the volume for device paths followed by any subsequent separator. Examples: * Unix: * `/foo/bar => /` * `foo/bar => nil` * Windows: * `C:\foo\bar => C:\` * `C:foo\bar => C:` * `\foo\bar => \ ` * `foo\bar => nil` * `\\server\share\file => \\server\share\` * `\\?\UNC\server\share\file => \\?\UNC\server\share\` * `\\.\device\folder => \\.\device\` Setting the root to `nil` will remove the root and setting a new root will replace the root. Example: var path: FilePath = "/foo/bar" path.root = nil // path is "foo/bar" path.root = "/" // path is "/foo/bar" Example (Windows): var path: FilePath = #"\foo\bar"# path.root = nil // path is #"foo\bar"# path.root = "C:" // path is #"C:foo\bar"# path.root = #"C:\"# // path is #"C:\foo\bar"#

set · iOS 15.0+

root

TypeScript

set root(value: (FilePath_Root) | null)

Swift declaration

var root: FilePath.Root? { get set }

init · iOS 15.0+

init

TypeScript

static initRoot(root: (FilePath_Root) | null, components: SDKHandle): FilePath

Swift declaration

init(root: FilePath.Root?, _ components: FilePath.ComponentView.SubSequence)

Create a file path from an optional root and a slice of another path's components.

init · iOS 15.0+

init

TypeScript

static initRoot46201(root: (FilePath_Root) | null, components: Array<FilePath_Component>): FilePath

Swift declaration

init<C>(root: FilePath.Root?, _ components: C) where C : Collection, C.Element == FilePath.Component

Create a file path from a root and a collection of components.

method · iOS 27.0+

stat

TypeScript

statRelativeToFlagsRetryOnInterrupt(fd: FileDescriptor, flags: Stat_Flags, retryOnInterrupt?: boolean): Stat

Swift declaration

func stat(relativeTo fd: FileDescriptor, flags: Stat.Flags, retryOnInterrupt: Bool = true) throws(Errno) -> Stat

Creates a `Stat` struct for the file referenced by this `FilePath` using the given `Flags`, including a `FileDescriptor` to resolve a relative path. If `path` is absolute (starts with a forward slash), then `fd` is ignored. If `path` is relative, it is resolved against the directory given by `fd`. The corresponding C function is `fstatat()`.

method · iOS 27.0+

stat

TypeScript

statFollowTargetSymlinkRetryOnInterrupt(followTargetSymlink?: boolean, retryOnInterrupt?: boolean): Stat

Swift declaration

func stat(followTargetSymlink: Bool = true, retryOnInterrupt: Bool = true) throws(Errno) -> Stat

Creates a `Stat` struct for the file referenced by this `FilePath`. `followTargetSymlink` determines the behavior if `path` ends with a symbolic link. By default, `followTargetSymlink` is `true` and this initializer behaves like `stat()`. If `followTargetSymlink` is set to `false`, this initializer behaves like `lstat()` and returns information about the symlink itself. The corresponding C function is `stat()` or `lstat()` as described above.

method · iOS 27.0+

stat

TypeScript

statFlagsRetryOnInterrupt(flags: Stat_Flags, retryOnInterrupt?: boolean): Stat

Swift declaration

func stat(flags: Stat.Flags, retryOnInterrupt: Bool = true) throws(Errno) -> Stat

Creates a `Stat` struct for the file referenced by this `FilePath` using the given `Flags`. If `path` is relative, it is resolved against the current working directory. The corresponding C function is `fstatat()`.

get · iOS 15.0+

stem

TypeScript

get stem(): (string) | null

Swift declaration

var stem: String? { get }

The non-extension portion of the file or directory last component. Returns `nil` if `lastComponent` is `nil` * `/tmp/foo.txt => foo` * `/Applications/Foo.app/ => Foo` * `/Applications/Foo.app/bar.txt => bar` * `/tmp/.hidden => .hidden` * `/tmp/.. => ..` * `/ => nil`

method · iOS 15.0+

append

TypeScript

append(component: FilePath_Component): void

Swift declaration

mutating func append(_ component: FilePath.Component)

Append a `component` on to the end of this path. Example: var path: FilePath = "/tmp" let sub: FilePath = "foo/./bar/../baz/." for comp in sub.components.filter({ $0.kind != .currentDirectory }) { path.append(comp) } // path is "/tmp/foo/bar/../baz"

method · iOS 15.0+

append

TypeScript

append2980(other: string): void

Swift declaration

mutating func append(_ other: String)

Append the contents of `other`, ignoring any spurious leading separators. A leading separator is spurious if `self` is non-empty. Example: var path: FilePath = "" path.append("/var/www/website") // "/var/www/website" path.append("static/assets") // "/var/www/website/static/assets" path.append("/main.css") // "/var/www/website/static/assets/main.css"

method · iOS 15.0+

append

TypeScript

append3484(components: Array<FilePath_Component>): void

Swift declaration

mutating func append<C>(_ components: C) where C : Collection, C.Element == FilePath.Component

Append `components` on to the end of this path. Example: var path: FilePath = "/" path.append(["usr", "local"]) // path is "/usr/local" let otherPath: FilePath = "/bin/ls" path.append(otherPath.components) // path is "/usr/local/bin/ls"

get · iOS 14.0+

length

TypeScript

get length(): number

Swift declaration

var length: Int { get }

The length of the file path, excluding the null terminator.

method · iOS 15.0+

starts

TypeScript

starts(other: FilePath): boolean

Swift declaration

func starts(with other: FilePath) -> Bool

Returns whether `other` is a prefix of `self`, only considering whole path components. Example: let path: FilePath = "/usr/bin/ls" path.starts(with: "/") // true path.starts(with: "/usr/bin") // true path.starts(with: "/usr/bin/ls") // true path.starts(with: "/usr/bin/ls///") // true path.starts(with: "/us") // false

get · iOS 15.0+

string

TypeScript

get string(): string

Swift declaration

var string: String { get }

Creates a string by interpreting the path’s content as UTF-8 on Unix and UTF-16 on Windows. This property is equivalent to calling `String(decoding: path)`

init · iOS 14.0+ · Deprecated in iOS 15.0

init

TypeScript

static initCString(cString: SDKHandle): FilePath

Swift declaration

init(cString: UnsafePointer<CChar>)

For backwards compatibility only. This initializer is equivalent to the preferred `FilePath(platformString:)`.

init · iOS 14.0+

init

TypeScript

static initCString90738(cString: string): FilePath

Swift declaration

@backDeployed(before: macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0)
init(cString: String)

init · iOS 14.0+

init

TypeScript

static initCString59262(cString: Array<number>): FilePath

Swift declaration

@backDeployed(before: macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0)
init(cString: [CChar])

init · iOS 14.0+

init

TypeScript

static initCString93128(cString: number): { $ret: FilePath; $out: { "cString": number } }

Swift declaration

@backDeployed(before: macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0)
init(cString: inout CChar)

Omit the output parameters from the call. The result contains $ret and $out, with cString inside $out.

get · iOS 15.0+

isEmpty

TypeScript

get isEmpty(): boolean

Swift declaration

var isEmpty: Bool { get }

Whether this path is empty

method · iOS 15.0+

pushing

TypeScript

pushing(other: FilePath): FilePath

Swift declaration

func pushing(_ other: FilePath) -> FilePath

Non-mutating version of `push()`.

method · iOS 15.0+

appending

TypeScript

appending(other: FilePath_Component): FilePath

Swift declaration

func appending(_ other: FilePath.Component) -> FilePath

Non-mutating version of `append(_:Component)`.

method · iOS 15.0+

appending

TypeScript

appending55732(other: string): FilePath

Swift declaration

func appending(_ other: String) -> FilePath

Non-mutating version of `append(_:String)`.

method · iOS 15.0+

appending

TypeScript

appending13260(components: Array<FilePath_Component>): FilePath

Swift declaration

func appending<C>(_ components: C) -> FilePath where C : Collection, C.Element == FilePath.Component

Non-mutating version of `append(_:C)`.

get · iOS 15.0+

extension

TypeScript

get extension(): (string) | null

Swift declaration

var `extension`: String? { get set }

The extension of the file or directory last component. If `lastComponent` is `nil` or one of the special path components `.` or `..`, `get` returns `nil` and `set` does nothing. If `lastComponent` does not contain a `.` anywhere, or only at the start, `get` returns `nil` and `set` will append a `.` and `newValue` to `lastComponent`. Otherwise `get` returns everything after the last `.` and `set` will replace the extension. Examples: * `/tmp/foo.txt => txt` * `/Applications/Foo.app/ => app` * `/Applications/Foo.app/bar.txt => txt` * `/tmp/foo.tar.gz => gz` * `/tmp/.hidden => nil` * `/tmp/.hidden. => ""` * `/tmp/.. => nil` Example: var path = "/tmp/file" path.extension = "txt" // path is "/tmp/file.txt" path.extension = "o" // path is "/tmp/file.o" path.extension = nil // path is "/tmp/file" path.extension = "" // path is "/tmp/file."

set · iOS 15.0+

extension

TypeScript

set extension(value: (string) | null)

Swift declaration

var `extension`: String? { get set }

method · iOS 15.0+

removeAll

TypeScript

removeAll(keepingCapacity?: boolean): void

Swift declaration

mutating func removeAll(keepingCapacity: Bool = false)

Remove the contents of the path, keeping the null terminator.

init · iOS 14.0+

init

TypeScript

static init(): FilePath

Swift declaration

init()

Creates an empty, null-terminated path.

init · iOS 14.0+

init

TypeScript

static init73031(string: string): FilePath

Swift declaration

init(_ string: String)

Creates a file path from a string. - Parameter string: A string whose Unicode encoded contents to use as the contents of the path.

Skipped declarations

1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.

FilePath.init(root:components:)

A variable number of Swift arguments is not supported.

All System types →