14.1.1 Manipulating Paths

Beware that the current locale might not encode every string, in which case string->path can produce the same path for different strs. See also string->path-element, which should be used instead of string->path when a string represents a single path element.

See also string->some-system-path.

For converting relative path elements from literals, use instead bytes->path-element, which applies a suitable encoding for individual elements.

The resulting string is suitable for displaying to a user, string-ordering comparisons, etc., but it is not suitable for re-creating a path (possibly modified) via string->path, since decoding and re-encoding the path’s byte string may lose information.

Furthermore, for display and sorting based on individual path elements (such as pathless file names), use path-element->string, instead, to avoid special encodings use to represent some relative paths. See Windows Path Conventions for specific information about the conversion of Windows paths.

See also some-system-path->string.

Conversion to and from byte values is useful for marshaling and unmarshaling paths, but manipulating the byte form of a path is generally a mistake. In particular, the byte string may start with a \\?\REL encoding for Windows paths. Instead of path->bytes, use split-path and path-element->bytes to manipulate individual path elements.

If str does not correspond to any path element (e.g., it is an absolute path, or it can be split), or if it corresponds to an up-directory or same-directory indicator on Unix and Mac OS X, then exn:fail:contract exception is raised.

As for path->string, information can be lost from str in the locale-specific conversion to a path.

The bytes->path-element procedure is generally the best choice for reconstructing a path based on another path (where the other path is deconstructed with split-path and path-element->bytes) when ASCII-level manipulation of path elements is necessary.

The path argument must be such that split-path applied to path would return 'relative as its first result and a path as its second result, otherwise the exn:fail:contract exception is raised.

The path-element->string procedure is generally the best choice for presenting a pathless file or directory name to a user.

For any reasonable locale, consecutive ASCII characters in the printed form of path are mapped to consecutive byte values that match each character’s code-point value, and a leading or trailing ASCII character is mapped to a leading or trailing byte, respectively. The path argument can be a path for any platform.

The path-element->bytes procedure is generally the right choice (in combination with split-path) for extracting the content of a path to manipulate it at the ASCII level (then reassembling the result with bytes->path-element and build-path).

The base and each sub must be either a relative path, the symbol 'up (indicating the relative parent directory), or the symbol 'same (indicating the relative current directory). For Windows paths, if base is a drive specification (with or without a trailing slash) the first sub can be an absolute (driveless) path. For all platforms, the last sub can be a filename.

The base and sub arguments can be paths for any platform. The platform for the resulting path is inferred from the base and sub arguments, where string arguments imply a path for the current platform. If different arguments are for different platforms, the exn:fail:contract exception is raised. If no argument implies a platform (i.e., all are 'up or 'same), the generated path is for the current platform.

Each sub and base can optionally end in a directory separator. If the last sub ends in a separator, it is included in the resulting path.

If base or sub is an illegal path string (because it is empty or contains a nul character), the exn:fail:contract exception is raised.

The build-path procedure builds a path without checking the validity of the path or accessing the filesystem.

See Unix and Mac OS X Paths for more information on the construction of Unix and Mac OS X paths, and see Windows Path Conventions for more information on the construction of Windows paths.

The following examples assume that the current directory is "/home/joeuser" for Unix examples and "C:\Joe’s Files" for Windows examples.

(define p1 (build-path (current-directory) "src" "racket"))

; Unix: p1 is "/home/joeuser/src/racket"

; Windows: p1 is "C:\\Joe's Files\\src\\racket"

(define p2 (build-path 'up 'up "docs" "Racket"))

; Unix: p2 is "../../docs/Racket"

; Windows: p2 is "..\\..\\docs\\Racket"

(build-path p2 p1)

; Unix and Windows: raises exn:fail:contract; p1 is absolute

(build-path p1 p2)

; Unix: is "/home/joeuser/src/racket/../../docs/Racket"

; Windows: is "C:\\Joe's Files\\src\\racket\\..\\..\\docs\\Racket"

This procedure does not access the filesystem.

The path and base arguments can be paths for any platform; if they are for different platforms, the exn:fail:contract exception is raised.

This procedure does not access the filesystem.

This procedure does not access the filesystem.

In general, the pathname is normalized as much as possible—without consulting the filesystem if use-filesystem? is #f, and (on Windows) without changing the case of letters within the path. If path syntactically refers to a directory, the result ends with a directory separator.

When path is simplified and use-filesystem? is true (the default), a complete path is returned; if path is relative, it is resolved with respect to the current directory, and up-directory indicators are removed taking into account soft links (so that the resulting path refers to the same directory as before).

When use-filesystem? is #f, up-directory indicators are removed by deleting a preceding path element, and the result can be a relative path with up-directory indicators remaining at the beginning of the path; up-directory indicators are dropped when they refer to the parent of a root directory. Similarly, the result can be the same as (build-path 'same) (but with a trailing separator) if eliminating up-directory indicators leaves only same-directory indicators.

The path argument can be a path for any platform when use-filesystem? is #f, and the resulting path is for the same platform.

The filesystem might be accessed when use-filesystem? is true, but the source or simplified path might be a non-existent path. If path cannot be simplified due to a cycle of links, the exn:fail:filesystem exception is raised (but a successfully simplified path may still involve a cycle of links if the cycle did not inhibit the simplification).

See Unix and Mac OS X Paths for more information on simplifying Unix and Mac OS X paths, and see Windows Path Conventions for more information on simplifying Windows paths.

The path argument can be a path for any platform, but beware that local-sensitive decoding and conversion of the path may be different on the current platform than for the path’s platform.

This procedure does not access the filesystem.

• base is either

  • a path,

  • 'relative if path is an immediate relative directory or filename, or

  • #f if path is a root directory.

• name is either

  • a directory-name path,

  • a filename,

  • 'up if the last part of path specifies the parent directory of the preceding path (e.g., .. on Unix), or

  • 'same if the last part of path specifies the same directory as the preceding path (e.g., . on Unix).

• must-be-dir? is #t if path explicitly specifies a directory (e.g., with a trailing separator), #f otherwise. Note that must-be-dir? does not specify whether name is actually a directory or not, but whether path syntactically specifies a directory.

Compared to path, redundant separators (if any) are removed in the result base and name. If base is #f, then name cannot be 'up or 'same. The path argument can be a path for any platform, and resulting paths for the same platform.

This procedure does not access the filesystem.

See Unix and Mac OS X Paths for more information on splitting Unix and Mac OS X paths, and see Windows Path Conventions for more information on splitting Windows paths.

If path is not already complete, is it completed via path->complete-path, in which case path must be a path for the current platform. The path argument is also cleansed and case-normalized via normal-case-path. The path is then appended to root-path; in the case of Windows paths, a root letter drive becomes a letter path element, while a root UNC path is prefixed with "UNC" as a path element and the machine and volume names become path elements.