15.1.1 Manipulating Paths
procedure
(path-string? v) → boolean?
v : any/c 
procedure
v : any/c 
procedure
(string->path str) → path?
str : string? 
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.
procedure
(bytes->path bstr [type]) → path?
bstr : bytes? type : (or/c 'unix 'windows) = (system-path-convention-type) 
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.
procedure
(path->string path) → string?
path : path? 
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.
procedure
(path->bytes path) → bytes?
path : path-for-some-system? 
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.
procedure
(string->path-element str) → path?
str : string? 
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.
Like path->string, information can be lost from str in the locale-specific conversion to a path.
procedure
(bytes->path-element bstr [type]) → path-for-some-system?
bstr : bytes? type : (or/c 'unix 'windows) = (system-path-convention-type) 
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.
procedure
(path-element->string path) → string?
path : path-element? 
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.
procedure
(path-element->bytes path) → bytes?
path : path-element? 
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).
procedure
(path-convention-type path) → (or/c 'unix 'windows)
path : path-for-some-system? 
procedure
(system-path-convention-type) → (or/c 'unix 'windows)
procedure
(build-path base sub ...) → path-for-some-system?
base : (or/c path-string? path-for-some-system? 'up 'same) 
sub : 
(or/c (and/c (or/c path-string? path-for-some-system?) (not/c complete-path?)) (or/c 'up 'same)) 
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 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" 
procedure
(build-path/convention-type type base sub ...) → path-for-some-system? type : (or/c 'unix 'windows) base : (or/c path-string? path-for-some-system? 'up 'same) 
sub : 
(or/c (and/c (or/c path-string? path-for-some-system?) (not/c complete-path?)) (or/c 'up 'same)) 
procedure
(absolute-path? path) → boolean?
path : (or/c path-string? path-for-some-system?) 
procedure
(relative-path? path) → boolean?
path : (or/c path-string? path-for-some-system?) 
procedure
(complete-path? path) → boolean?
path : (or/c path-string? path-for-some-system?) 
This procedure does not access the filesystem.
procedure
(path->complete-path path [base]) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) 
base : (or/c path-string? path-for-some-system?) = (current-directory) 
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.
procedure
path : (or/c path-string? path-for-some-system?) 
This procedure does not access the filesystem.
procedure
(resolve-path path) → path?
path : path-string? 
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.
procedure
(cleanse-path path) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) 
procedure
(expand-user-path path) → path?
path : path-string? 
procedure
(simplify-path path [use-filesystem?]) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) use-filesystem? : boolean? = #t 
In general, the pathname is normalized as much as possible—
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. On Unix and Mac OS X, 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 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 X Paths and Windows Paths for more information on simplifying paths.
procedure
(normal-case-path path) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) 
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.
procedure
(split-path path) → 
(or/c path-for-some-system? 'relative #f) (or/c path-for-some-system? 'up 'same) boolean? path : (or/c path-string? path-for-some-system?) 
- base is either 
- 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 and Windows Paths for more information on splitting paths.
procedure
(explode-path path)
→ (listof (or/c path-for-some-system? 'up 'same)) path : (or/c path-string? path-for-some-system?) 
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).
procedure
(path-replace-suffix path suffix) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) suffix : (or/c string? bytes?) 
procedure
(path-add-suffix path suffix) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) suffix : (or/c string? bytes?) 
procedure
(reroot-path path root-path) → path-for-some-system?
path : (or/c path-string? path-for-some-system?) root-path : (or/c path-string? path-for-some-system?) 
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.
| Examples: | ||||||||||||
| 
 |