std.path

Lexical operations on paths held as strings. There is no Path type: a path is the text the system takes, and these functions take it apart and put it together without touching the file system: join, normalize, fileName, parent, extension, stem, withExtension, isAbsolute, relative, components and separator. fs.absolute(p), which needs the working directory, is the one that asks the system.

On Windows both \ and / separate, a path may start with a volume — a drive, C:, or a UNC share, \\server\share — and names compare without regard to the case of ASCII letters; what these functions build, they build with \. Elsewhere / separates and names compare exactly.

Examples

import std.io { println };
import std.path;

let p = path.normalize("docs/./book/../guide/intro.md");
println(path.components(p).iter().join(" "));
println(path.fileName(p));
println(path.extension(p));
println(path.fileName(path.withExtension(p, "html")));

docs guide intro.md
intro.md
.md
intro.html

Functions

pub fn join(parts: string...): string

Returns parts joined by the separator, with empty parts left out and the result normalized; the empty string when no part is non-empty. On Windows a drive alone, C:, joins without a separator — C:a, relative to the directory current on that drive.

pub fn normalize(p: StringView): string

Returns the shortest path that names what p names, lexically: runs of separators collapse, . elements are dropped, a .. removes the element before it — at the root it is dropped, at the start of a relative path it is kept —, and no separator remains at the end but the root's. Returns . for an empty path.

pub fn fileName(p: StringView): string

Returns the last element of p, after dropping trailing separators. Returns . for an empty path and the separator for a path of separators alone.

pub fn parent(p: StringView): string

Returns all but the last element of p, normalized: . where no directory precedes it, the root for an element directly under the root.

pub fn extension(p: StringView): string

Returns the extension of the last element with its dot — .txt of notes.txt — or the empty string. It runs from the last dot of the last element, so of .bashrc it is all of it.

pub fn stem(p: StringView): string

Returns the last element without its extension: notes of a/notes.txt.

pub fn withExtension(p: StringView, ext: StringView): string

Returns p with its extension replaced by ext, adding the dot where ext lacks one, or with the extension removed for an empty ext: withExtension("a/notes.txt", ".md") is a/notes.md.

pub fn isAbsolute(p: StringView): bool

Returns whether p names the same place from every working directory: it starts with the root; on Windows with a drive and the root, or with a UNC share — \a alone is relative there, to the current drive.

pub fn relative(base: StringView, target: StringView): ?string

Returns the path that names target from base, lexically: relative("/a", "/a/b/c") is b/c, relative("/a", "/b") is ../b, and . for the same place. Returns null where there is none — one absolute and the other not, different volumes, or a base whose remaining part starts with ...

pub fn components(p: StringView): string[]

Returns the parts of p in order, lexically and without normalizing: the root first where there is one — /, on Windows the volume with it, C:\ —, then each element, with empty elements and . left out and .. kept.

Constants

pub let separator: string = if (onWindows) "\\" else "/"

The separator the system writes: \ on Windows, / elsewhere.