STRUCT

UNIXPath

Contents

• Properties
  • relativeToRootPrefix
  • pathString
  • clearPathString
  • root
  • dirname
  • pathType
  • isAbsolute
  • isRelative
  • isRelativeToRoot
  • isRoot
  • basename
  • basenameWithoutExt
  • components
  • parentDirectory
  • suffix
  • extension
• Methods
  • isValidComponent(_:)
  • init(validating:)
  • init(_:_:)
  • init(_:validating:)
  • init(validating:relativeTo:)
  • init(validatingAbsolutePath:)
  • init(validatingRelativePath:)
  • init(validatingRelativeToRootPath:)
  • suffix(withDot:)
  • appending(component:)
  • appending(components:)
  • appending(components:)
  • appending(_:)
  • relative(to:)
  • isAncestor(of:)
  • isAncestorOfOrEqual(to:)
  • isDescendant(of:)
  • isDescendantOfOrEqual(to:)

public struct UNIXPath: Sendable, Hashable

Represents an absolute or relative file system path, independently of what (or whether anything at all) exists at that path in the file system at any given time.

An absolute path always starts with a / character, and holds a normalized string representation. This normalization is strictly syntactic, and does not access the file system in any way. As with AbsolutePath, the normalization for relative path is strictly syntactic, and does not access the file system in any way.

The absolute path string is normalized by:

• Collapsing .. path components
• Removing . path components
• Removing any trailing path separator
• Removing any redundant path separators

The relative path string is normalized by:

• Collapsing .. path components that aren't at the beginning
• Removing extraneous . path components
• Removing any trailing path separator
• Removing any redundant path separators
• Replacing a completely empty path with a .

This string manipulation may change the meaning of a path if any of the path components are symbolic links on disk. However, the file system is never accessed in any way when initializing a path.

Note that ~ (home directory resolution) is not done as part of path normalization, because it is normally the responsibility of the shell and not the program being invoked (e.g. when invoking cd ~, it is the shell that evaluates the tilde; the cd command receives an absolute path).

Properties

relativeToRootPrefix

public static let relativeToRootPrefix = "@/"

pathString

public let pathString: String

clearPathString

public var clearPathString: String

Path without prefixes, such as '@/' for relativeToRoot paths

root

public static let root = Self(pathString: "/")

dirname

public var dirname: String

Directory component. An absolute path always has a non-empty directory component (the directory component of the root path is the root itself).

pathType

public var pathType: PathType

isAbsolute

public var isAbsolute: Bool

isRelative

public var isRelative: Bool

isRelativeToRoot

public var isRelativeToRoot: Bool

isRoot

public var isRoot: Bool

True if the path is the root directory.

basename

public var basename: String

Last path component (including the suffix, if any). It is never empty.

basenameWithoutExt

public var basenameWithoutExt: String

Returns the basename without the extension.

components

public var components: [String]

Returns an array of strings that make up the path components of the relative path. This is the same sequence of strings as the basenames of each successive path component. Therefore the returned array of path components is never empty; even an empty path has a single path component: the . string.

parentDirectory

public var parentDirectory: Self

Absolute path of parent directory. This always returns a path, because every directory has a parent (the parent directory of the root directory is considered to be the root directory itself).

suffix

public var suffix: String?

Suffix (including leading . character) if any. Note that a basename that starts with a . character is not considered a suffix, nor is a trailing . character.

extension

public var `extension`: String?

Extension of the give path's basename. This follow same rules as suffix except that it doesn't include leading . character.

Methods

isValidComponent(_:)

public static func isValidComponent(_ name: String) -> Bool

Check if the given name is a valid individual path component.

This only checks with regard to the semantics enforced by absolute path and relative path; particular file systems may have their own additional requirements.

init(validating:)

public init(validating path: String) throws

Convenience initializer that validated the path

init(_:_:)

public init(_ absPath: AbsolutePath, _ relPath: RelativePath)

Initializes absolute path by concatenating a relative path to an existing absolute path, and renormalizing if necessary.

init(_:validating:)

public init(_ absPath: AbsolutePath, validating relStr: String) throws

Convenience initializer that appends a string to a relative path.

init(validating:relativeTo:)

public init(validating str: String, relativeTo basePath: AbsolutePath) throws

Initializes an absolute path from a string that may be either absolute or relative; if relative, basePath is used as the anchor; if absolute, it is used as is, and in this case basePath is ignored.

init(validatingAbsolutePath:)

public init(validatingAbsolutePath path: String) throws

Initializes absolute path from path, which must be an absolute path (i.e. it must begin with a path separator; this initializer does not interpret leading ~ characters as home directory specifiers). The input string will be normalized if needed, as described in the documentation for UNIXPath.

init(validatingRelativePath:)

public init(validatingRelativePath path: String) throws

Convenience initializer that verifies that the path is relative.

init(validatingRelativeToRootPath:)

public init(validatingRelativeToRootPath path: String) throws

Convenience initializer that verifies that the path is relative to root

suffix(withDot:)

public func suffix(withDot: Bool) -> String?

Suffix with or without leading . character if any. Note that a basename that starts with a . character is not considered a suffix, nor is a trailing . character.

appending(component:)

public func appending(component name: String) -> Self

Returns path with an additional literal component appended.

This method accepts pseudo-path like '.' or '..', but should not contain "/".

appending(components:)

public func appending(components names: [String]) -> UNIXPath

Returns path with additional literal components appended.

This method should only be used in cases where the input is guaranteed to be a valid path component (i.e., it cannot be empty, contain a path separator, or be a pseudo-path like '.' or '..').

appending(components:)

public func appending(components names: String...) -> UNIXPath

Returns path with additional literal components appended.

This method should only be used in cases where the input is guaranteed to be a valid path component (i.e., it cannot be empty, contain a path separator, or be a pseudo-path like '.' or '..').

appending(_:)

public func appending(_ relativePath: Self) -> Self

Returns path with the relative path applied.

relative(to:)

public func relative(to base: AbsolutePath) -> RelativePath

Returns a relative path that, when concatenated to base, yields the callee path itself. If base is not an ancestor of the callee, the returned path will begin with one or more .. path components.

Because both paths are absolute, they always have a common ancestor (the root path, if nothing else). Therefore, any path can be made relative to any other path by using a sufficient number of .. path components.

This method is strictly syntactic and does not access the file system in any way. Therefore, it does not take symbolic links into account.

isAncestor(of:)

public func isAncestor(of descendant: AbsolutePath) -> Bool

Returns true if the path is an ancestor of the given path.

This method is strictly syntactic and does not access the file system in any way.

isAncestorOfOrEqual(to:)

public func isAncestorOfOrEqual(to descendant: AbsolutePath) -> Bool

Returns true if the path is an ancestor of or equal to the given path.

This method is strictly syntactic and does not access the file system in any way.

isDescendant(of:)

public func isDescendant(of ancestor: AbsolutePath) -> Bool

Returns true if the path is a descendant of the given path.

This method is strictly syntactic and does not access the file system in any way.

isDescendantOfOrEqual(to:)

public func isDescendantOfOrEqual(to ancestor: AbsolutePath) -> Bool

Returns true if the path is a descendant of or equal to the given path.

This method is strictly syntactic and does not access the file system in any way.