Path

class Path : Comparable<Path>

A hierarchical address on a file system. A path is an identifier only; a FileSystem is required to access the file that a path refers to, if any.

UNIX and Windows Paths

----------------------

Paths follow different rules on UNIX vs. Windows operating systems. On UNIX operating systems (including Linux, Android, macOS, and iOS), the / slash character separates path segments. On Windows, the \ backslash character separates path segments. The two platforms each have their own rules for path resolution. This class implements all rules on all platforms; for example you can model a Linux path in a native Windows application.

Absolute and Relative Paths

---------------------------

  • Absolute paths identify a location independent of any working directory. On UNIX, absolute paths are prefixed with a slash, /. On Windows, absolute paths are one of two forms. The first is a volume letter, a colon, and a backslash, like C:\. The second is called a Universal Naming Convention (UNC) path, and it is prefixed by two backslashes \\. The term ‘fully-qualified path’ is a synonym of ‘absolute path’.

  • Relative paths are everything else. On their own, relative paths do not identify a location on a file system; they are relative to the system's current working directory. Use FileSystem.canonicalize to convert a relative path to its absolute path on a particular file system.

There are some special cases when working with relative paths.

On Windows, each volume (like A:\ and C:\) has its own current working directory. A path prefixed with a volume letter and colon but no slash (like A:letter.doc) is relative to the working directory on the named volume. For example, if the working directory on A:\ is A:\jesse, then the path A:letter.doc resolves to A:\jesse\letter.doc.

The path string C:\Windows is an absolute path when following Windows rules and a relative path when following UNIX rules. For example, if the current working directory is /Users/jesse, then C:\Windows resolves to /Users/jesse/C:/Windows.

This class decides which rules to follow by inspecting the first slash character in the path string. If the path contains no slash characters, it uses the host platform's rules. Or you may explicitly specify which rules to use by specifying the directorySeparator parameter in toPath. Pass "/" to get UNIX rules and "\" to get Windows rules.

Path Traversal

--------------

After the optional path root (like / on UNIX, like X:\ or \\ on Windows), the remainder of the path is a sequence of segments separated by / or \ characters. Segments satisfy these rules:

  • Segments are always non-empty.

  • If the segment is ., then the full path must be ..

  • If the segment is .., then the the path must be relative. All .. segments precede all other segments.

The only path that ends with / is the file system root, /. The dot path . is a relative path that resolves to whichever path it is resolved against.

The name is the last segment in a path. It is typically a file or directory name, like README.md or Desktop. The name may be another special value:

  • The empty string is the name of the file system root path (full path /).

  • . is the name of the identity relative path (full path .).

  • .. is the name of a path consisting of only .. segments (such as ../../..).

Comparing Paths

---------------

Path implements Comparable, equals, and hashCode. If two paths are equal then they operate on the same file on the file system.

Note that the converse is not true: if two paths are non-equal, they may still resolve to the same file on the file system. Here are some of the ways non-equal paths resolve to the same file:

  • Case differences. The default file system on macOS is case-insensitive. The paths /Users/jesse/notes.txt and /USERS/JESSE/NOTES.TXT are non-equal but these paths resolve to the same file.

  • Mounting differences. Volumes may be mounted at multiple paths. On macOS, /Users/jesse/notes.txt and /Volumes/Macintosh HD/Users/jesse/notes.txt typically resolve to the same file. On Windows, C:\project\notes.txt and \\localhost\c$\project\notes.txt typically resolve to the same file.

  • Hard links. UNIX file systems permit multiple paths to refer for same file. The paths may be wildly different, like /Users/jesse/bruce_wayne.vcard and /Users/jesse/batman.vcard, but changes via either path are reflected in both.

  • Symlinks. Symlinks permit multiple paths and directories to refer to the same file. On macOS /tmp is symlinked to /private/tmp, so /tmp/notes.txt and /private/tmp/notes.txt resolve to the same file.

To test whether two paths refer to the same file, try FileSystem.canonicalize first. This follows symlinks and looks up the preserved casing for case-insensitive case-preserved paths. This method does not guarantee a unique result, however. For example, each hard link to a file may return its own canonical path.

Paths are sorted in case-sensitive order.

Sample Paths

------------

<table> <tr><th> Path <th> Parent <th> Name <th> Notes </tr> <tr><td> `/` <td> null <td> (empty) <td> root </tr> <tr><td> `/home/jesse/notes.txt` <td> `/home/jesse` <td> `notes.txt` <td> absolute path </tr> <tr><td> `project/notes.txt` <td> `project` <td> `notes.txt` <td> relative path </tr> <tr><td> `../../project/notes.txt` <td> `../../project` <td> `notes.txt` <td> relative path with traversal </tr> <tr><td> `../../..` <td> null <td> `..` <td> relative path with traversal </tr> <tr><td> `.` <td> null <td> `.` <td> current working directory </tr> <tr><td> `C:\` <td> null <td> (empty) <td> volume root (Windows) </tr> <tr><td> `C:\Windows\notepad.exe` <td> `C:\Windows` <td> `notepad.exe` <td> volume absolute path (Windows) </tr> <tr><td> `\` <td> null <td> (empty) <td> absolute path (Windows) </tr> <tr><td> `\Windows\notepad.exe` <td> `\Windows` <td> `notepad.exe` <td> absolute path (Windows) </tr> <tr><td> `C:` <td> null <td> (empty) <td> volume-relative path (Windows) </tr> <tr><td> `C:project\notes.txt` <td> `C:project` <td> `notes.txt` <td> volume-relative path (Windows) </tr> <tr><td> `\\server` <td> null <td> `server` <td> UNC server (Windows) </tr> <tr><td> `\\server\project\notes.txt` <td> `\\server\project` <td> `notes.txt` <td> UNC absolute path (Windows) </tr> </table>

class Path : Comparable<Path>

Types

Companion
Link copied to clipboard
common
object Companion

Functions

compareTo
Link copied to clipboard
common
open operator override fun compareTo(other: Path): Int
div
Link copied to clipboard
common
operator fun div(child: String): Path
Returns a path that resolves child relative to this path.
@JvmName(name = "resolve")
operator fun div(child: String): Path
common
operator fun div(child: Path): Path
Returns a path that resolves child relative to this path.
@JvmName(name = "resolve")
operator fun div(child: Path): Path
equals
Link copied to clipboard
common
open operator override fun equals(other: Any?): Boolean
hashCode
Link copied to clipboard
common
open override fun hashCode(): Int
toFile
Link copied to clipboard
fun toFile(): File
toNioPath
Link copied to clipboard
@IgnoreJRERequirement()
fun toNioPath(): Path
toString
Link copied to clipboard
common
open override fun toString(): String

Properties

isAbsolute
Link copied to clipboard
val isAbsolute: Boolean
isRelative
Link copied to clipboard
val isRelative: Boolean
isRoot
Link copied to clipboard
val isRoot: Boolean
Returns true if this is an absolute path with no parent.
val isRoot: Boolean
name
Link copied to clipboard
val name: String
nameBytes
Link copied to clipboard
val nameBytes: ByteString
parent
Link copied to clipboard
val parent: Path?
Returns the path immediately enclosing this path.
val parent: Path?
volumeLetter
Link copied to clipboard
val volumeLetter: Char?
This is the volume letter like "C" on Windows paths that starts with a volume letter.
val volumeLetter: Char?