15.1 Paths

When a Racket procedure takes a filesystem path as an argument, the path can be provided either as a string or as an instance of the path datatype. If a string is provided, it is converted to a path using string->path. Beware that some paths may not be representable as strings; see Unix Path Representation and Windows Path Representation for more information. A Racket procedure that generates a filesystem path always generates a path value.

By default, paths are created and manipulated for the current platform, but procedures that merely manipulate paths (without using the filesystem) can manipulate paths using conventions for other supported platforms. The bytes->path procedure accepts an optional argument that indicates the platform for the path, either 'unix or 'windows. For other functions, such as build-path or simplify-path, the behavior is sensitive to the kind of path that is supplied. Unless otherwise specified, a procedure that requires a path accepts only paths for the current platform.

Two path values are equal? when they are use the same convention type and when their byte-string representations are equal?. A path string (or byte string) cannot be empty, and it cannot contain a nul character or byte. When an empty string or a string containing nul is provided as a path to any procedure except absolute-path?, relative-path?, or complete-path?, the exn:fail:contract exception is raised.

Most Racket primitives that accept paths first cleanse the path before using it. Procedures that build paths or merely check the form of a path do not cleanse paths, with the exceptions of cleanse-path, expand-user-path, and simplify-path. For more information about path cleansing and other platform-specific details, see Unix and Mac OS Paths and Windows Paths.