Skip to content

std::path

Paths, as Strings. A Nomi path uses / on every operating system, so a program and its tests behave the same everywhere: on Windows std::fs accepts \ too and returns /, and a drive is written C:/Users. These functions read the text alone; none of them looks at the file system, so a typed literal’s handler may call them.

path.join("data", "log.txt") // "data/log.txt"

path.parent("data/log.txt") // Some("data")

path.base("data/log.txt") // "log.txt"

path.extension("log.tar.gz") // Some("gz")

path.stem("log.txt") // "log"

path.clean("a/./b/../c") // "a/c"

path.is_absolute("/etc") // True

path.relative("/a/b", "/a/c/d") // Some("../c/d")

path.matches("src/**/*.nomi", "src/x/y.nomi") // True

Import with import std::path.

fn join(base: String, name: String) -> String

base and name joined with a /, then cleaned (clean). An empty side is left out, so join("", "a") is "a", and two empty sides are "".

path.join("data", "log.txt") // "data/log.txt"
assert join("data", "log.txt") == "data/log.txt"
assert join("data/", "/log.txt") == "data/log.txt"
assert join("a/b", "../c") == "a/c"
assert join("", "a") == "a"
assert join("/", "etc") == "/etc"
assert join("", "") == ""
fn join_all(parts: List<String>) -> String

Every part joined with /, then cleaned, leaving out the empty ones; "" when every part is empty.

path.join_all(["data", "2026", "log.txt"]) // "data/2026/log.txt"
assert join_all(["data", "2026", "log.txt"]) == "data/2026/log.txt"
assert join_all(["/srv", "", "www"]) == "/srv/www"
assert join_all([]) == ""
fn clean(p: String) -> String

The shortest path that names what p names, by reading the text alone: repeated /s become one, each . goes, and each .. takes away the name before it. A .. at the start of a relative path stays, and one right after the root goes. A trailing / goes, except on / itself. An empty path is ".". It cleans as Go’s path.Clean does.

path.clean("a/./b/../c") // "a/c"
assert clean("a/./b/../c") == "a/c"
assert clean("a//b/") == "a/b"
assert clean("../../a") == "../../a"
assert clean("/../a") == "/a"
assert clean("a/..") == "."
assert clean("") == "."
assert clean("/") == "/"
assert clean("./") == "."
fn is_absolute(p: String) -> Bool

Whether p starts at the root: / first, or a drive such as C:/.

path.is_absolute("/etc") // True
assert is_absolute("/etc")
assert is_absolute("C:/Users")
refute is_absolute("etc/hosts")
refute is_absolute("")
fn parent(p: String) -> Maybe<String>

The directory p is in, after cleaning it, or None when p names no directory above itself: a lone name, /, . or an empty path.

path.parent("data/log.txt") // Some("data")
assert parent("data/log.txt") == Some("data")
assert parent("/etc") == Some("/")
assert parent("a/b/") == Some("a")
assert parent("log.txt") == None
assert parent("/") == None
assert parent("") == None
fn base(p: String) -> String

The last name in p, after cleaning it: "log.txt" for "data/log.txt". / is "/", and an empty path is ".".

path.base("data/log.txt") // "log.txt"
assert base("data/log.txt") == "log.txt"
assert base("data/") == "data"
assert base("/") == "/"
assert base("") == "."
fn extension(p: String) -> Maybe<String>

What follows the last . in the last name of p, or None when there is none to follow. A name that starts with its only . (.bashrc) has no extension, and neither does a name that ends in ..

path.extension("log.tar.gz") // Some("gz")
assert extension("log.tar.gz") == Some("gz")
assert extension("data/notes.txt") == Some("txt")
assert extension("Makefile") == None
assert extension(".bashrc") == None
assert extension("x.") == None
fn stem(p: String) -> String

The last name in p without its extension (extension).

path.stem("log.txt") // "log"
assert stem("log.txt") == "log"
assert stem("data/log.tar.gz") == "log.tar"
assert stem(".bashrc") == ".bashrc"
assert stem("Makefile") == "Makefile"
fn relative(from: String, to: String) -> Maybe<String>

The path that leads from the directory from to to, both cleaned, or None when there is none to write: one is absolute and the other is not, or from climbs above where to starts with ..s it cannot undo. The same path is ".".

path.relative("/a/b", "/a/c/d") // Some("../c/d")
assert relative("/a/b", "/a/c/d") == Some("../c/d")
assert relative("a", "a/b/c") == Some("b/c")
assert relative("a/b", "a/b") == Some(".")
assert relative("a/b/c", "a") == Some("../..")
assert relative("/a", "b") == None
assert relative("../a", "b") == None
fn matches(pattern: String, p: String) -> Bool

Whether p matches the glob pattern, a name at a time. In a name, * matches any run of characters, ? any one, and [abc] one of a set, with ranges ([a-z]) and ! first for the characters not in it. A ** name matches any number of names, none included. A name that starts with . matches only a pattern name that starts with ., so * does not reach hidden files. Neither side is cleaned.

path.matches("src/**/*.nomi", "src/x/y.nomi") // True
assert matches("src/**/*.nomi", "src/x/y.nomi")
assert matches("src/**/*.nomi", "src/y.nomi")
assert matches("*.txt", "notes.txt")
refute matches("*.txt", "data/notes.txt")
assert matches("log-?.txt", "log-1.txt")
assert matches("[a-c]*", "beta")
refute matches("[!a-c]*", "beta")
refute matches("*", ".hidden")
assert matches(".*", ".hidden")
assert matches("**", "a/b/c")