15.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. For information on how strings and byte strings encode paths, see Unix Path Representation and Windows Path Representation.

See also string->some-system-path, and see Unix Path Representation and Windows Path Representation for information on how strings encode paths.

Changed in version 6.1.1.1 of package base: Changed Windows conversion to always use UTF-8.

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

For information on how byte strings encode paths, see Unix Path Representation and Windows Path Representation.

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 Paths for specific information about the conversion of Windows paths.

See also some-system-path->string.

Changed in version 6.1.1.1 of package base: Changed Windows conversion to always use UTF-8.

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.

For information on how byte strings encode paths, see Unix Path Representation and Windows Path Representation.

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, then either #f is returned or exn:fail:contract exception is raised. A #f is returned only when false-on-non-element? is true.

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

Changed in version 8.1.0.6 of package base: Added the false-on-non-element? argument.

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.

Changed in version 8.1.0.6 of package base: Added the false-on-non-element? argument.

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

Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.

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 Paths and Windows Paths for more information on the construction of 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"

Note that, just as with build-path, any string arguments for either base or sub will be implicitly converted into a path for the current platform before being combined with the others. For this reason, you cannot use this function to build paths from strings for any platform other than the current one; in such attempts, type does not match the inferred convention type for the strings and an exn:fail:contract exception is raised. (To create paths for foreign platforms, see bytes->path.)

The usefulness of build-path/convention-type over build-path is limited to cases where the sub-paths contain 'same or 'up elements.

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.

On Windows, the path for a link should be simplified syntactically, so that an up-directory indicator removes a preceding path element independent of whether the preceding element itself refers to a link. For relative-paths links, the path should be parsed specially; see Windows Paths for more information.

Changed in version 6.0.1.12 of package base: Added support for links on Windows.

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 other than just converting slashes to backslashes 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. On Unix and Mac OS, up-directory indicators are removed taking into account soft links (so that the resulting path refers to the same directory as before); on Windows, up-directory indicators are removed by deleting a preceding path element.

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 Paths and Windows Paths for more information on simplifying 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 Paths and Windows Paths for more information on splitting paths.

The explode-path function computes its result in time proportional to the length of path (unlike a loop in that uses split-path, which must allocate intermediate paths).

An extension is defined as a . that is not at the start of the path element followed by any number of non-. characters/bytes at the end of the path element, as long as the path element is not a directory indicator like "..".

The path argument can be a path for any platform, and the result is for the same platform. If path represents a root, the exn:fail:contract exception is raised. The given ext typically starts with ., but it is not required to start with an extension separator.

Added in version 6.5.0.3 of package base.

Added in version 6.5.0.3 of package base.
Changed in version 6.8.0.2: Added the sep optional argument.

Like path-replace-extension, but treats a leading . in a path element as an extension separator.

Like path-add-extension, but treats a leading . in a path element as an extension separator.

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.