Structureswift-system 1.3.2SystemPackage

FilePath

Represents a location in the file system.

struct FilePath

Mangled symbol

s13SystemPackage8FilePathVWhat are these?

FNV24: [4T70J]

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.

Citizens in SystemPackage

Conformances

protocol CustomDebugStringConvertible
A type with a customized textual representation suitable for debugging purposes.
protocol CustomStringConvertible
A type with a customized textual representation.
protocol Decodable
A type that can decode itself from an external representation.
protocol Encodable
A type that can encode itself to an external representation.
protocol Equatable
A type that can be compared for value equality.
protocol ExpressibleByExtendedGraphemeClusterLiteral
A type that can be initialized with a string literal containing a single extended grapheme cluster.
protocol ExpressibleByStringLiteral
A type that can be initialized with a string literal.
protocol ExpressibleByUnicodeScalarLiteral
A type that can be initialized with a string literal containing a single Unicode scalar value.
protocol Hashable
A type that can be hashed into a Hasher to produce an integer hash value.

Types

struct Component
Represents an individual, non-root component of a file path.
struct ComponentView
A bidirectional, range replaceable collection of the non-root components that make up a file path.
struct Root
Represents a root of a file path.

Type members

init()
Creates an empty, null-terminated path.
init(String)
Creates a file path from a string.
init(from: any Decoder) throws
init(platformString: UnsafePointer<CInterop.PlatformChar>)
Creates a file path by copying bytes from a null-terminated platform string.
init(platformString: [CInterop.PlatformChar])
Creates a file path by copying bytes from a null-terminated platform string.
init(root: Root?, ComponentView.SubSequence)
Create a file path from an optional root and a slice of another path’s components.
init<C>(root: Root?, C)
Create a file path from a root and a collection of components.
init(root: Root?, components: Component...)
Create a file path from a root and any number of components.
init(stringLiteral: String)
Creates a file path from a string literal.

Show obsolete interfaces (6)

init(cString: UnsafePointer<CChar>)
For backwards compatibility only. This initializer is equivalent to the preferred FilePath(platformString:).
init(cString: String)
init(cString: [CChar])
init(cString: inout CChar)
init(platformString: String)
init(platformString: inout CInterop.PlatformChar)

Instance members

var components: ComponentView
View the non-root components that make up this path.
var debugDescription: String
A textual representation of the file path, suitable for debugging.
var description: String
A textual representation of the file path.
var `extension`: String?
The extension of the file or directory last component.
var isAbsolute: Bool
Returns true if this path uniquely identifies the location of a file without reference to an additional starting location.
var isEmpty: Bool
Whether this path is empty
var isLexicallyNormal: Bool
Whether the path is in lexical-normal form, that is . and .. components have been collapsed lexically (i.e. without following symlinks).
var isRelative: Bool
Returns true if this path is not absolute (see isAbsolute).
var lastComponent: Component?
Returns the final component of the path. Returns nil if the path is empty or only contains a root.
var length: Int
The length of the file path, excluding the null terminator.
var root: FilePath.Root?
Returns the root of a path if there is one, otherwise nil.
var stem: String?
The non-extension portion of the file or directory last component.
var string: String
Creates a string by interpreting the path’s content as UTF-8 on Unix and UTF-16 on Windows.
func append(FilePath.Component)
Append a component on to the end of this path.
func append(String)
Append the contents of other, ignoring any spurious leading separators.
func append<C>(C)
Append components on to the end of this path.
func appending(Component) -> FilePath
Non-mutating version of append(_:Component).
func appending(String) -> FilePath
Non-mutating version of append(_:String).
func appending<C>(C) -> FilePath
Non-mutating version of append(_:C).
func ends(with: FilePath) -> Bool
Returns whether other is a suffix of self, only considering whole path components.
func lexicallyNormalize()
Collapse . and .. components lexically (i.e. without following symlinks).
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
func lexicallyResolving(FilePath) -> FilePath?
Create a new FilePath by resolving subpath relative to self, ensuring that the result is lexically contained within self.
func push(FilePath)
If other does not have a root, append each component of other. If other has a root, replaces self with other.
func pushing(FilePath) -> FilePath
Non-mutating version of push().
func removeAll(keepingCapacity: Bool)
Remove the contents of the path, keeping the null terminator.
func removeLastComponent() -> Bool
In-place mutating variant of removingLastComponent.
func removePrefix(FilePath) -> Bool
If prefix is a prefix of self, removes it and returns true. Otherwise returns false.
func removingLastComponent() -> FilePath
Creates a new path with everything up to but not including lastComponent.
func removingRoot() -> FilePath
Creates a new path containing just the components, i.e. everything after root.
func reserveCapacity(Int)
Reserve enough storage space to store minimumCapacity platform characters.
func starts(with: FilePath) -> Bool
Returns whether other is a prefix of self, only considering whole path components.
func withCString<Result>((UnsafePointer<CChar>) throws -> Result) rethrows -> Result
For backwards compatibility only. This function is equivalent to the preferred withPlatformString.
func withPlatformString<Result>((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.

Type features

init(extendedGraphemeClusterLiteral: Self.StringLiteralType)
init(unicodeScalarLiteral: Self.ExtendedGraphemeClusterLiteralType)
static func != (lhs: Self, rhs: Self) -> Bool
Returns a Boolean value indicating whether two values are not equal.

Extension in WebURLSystemExtras

Type members

init(url: WebURL) throws
Reconstructs a FilePath from its URL representation.