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 ..

• For normalized paths, if the segment is .., then the path must be relative. All .. segments precede all other segments. In all cases, a segment .. cannot be the first segment of an absolute path.

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