Mah
DocsStdlibBlogChangelog
GitHub
Menu
DocsStdlibBlogChangelog GitHub

  • std:math
  • std:random
  • std:collections
  • std:time

  • std:path
  • std:json
  • std:csv
  • std:regex
  • std:bytes
  • std:url

  • std:async
  • std:fs
  • std:process
  • std:thread

  • std:socket
  • std:http

  • std:reflect
  • std:test

Standard library / Text & data

std:path

File paths as plain Strings: joining, splitting into parts, normalizing, and working out relative paths. Nothing here touches the file system (for that, see std:fs), so these functions never throw and work the same for paths that don’t exist.

import path from "std:path"

let p = path.join("src", "lib/util.mh")
print(p, path.dirname(p), path.basename(p))     # src/lib/util.mh src/lib util.mh
print(path.stem(p), path.extension(p))          # util .mh

Input may use / or \ and start with a drive (C:), so Windows paths work too. normalize, relative and join answer with /.

Building paths

join(a, b) puts a separator between two parts. If b is absolute, it replaces a, just as cd would. join_all joins a whole Vector left to right. Neither normalizes:

import path from "std:path"

print(path.join("a/b", "c"), path.join("a/b", "/etc/hosts"))   # a/b/c /etc/hosts
print(path.join_all(["home", "ann", "notes.txt"]))           # home/ann/notes.txt
print(path.join("a", "../b"))                                # a/../b

Taking paths apart

FunctionFor "docs/archive/report.tar.gz"
dirname(p)docs/archive
basename(p)report.tar.gz
extension(p).gz (from the last .)
stem(p)report.tar

A name that only starts with a dot, like .bashrc, has no extension. dirname of a bare name is ".", and basename of a root is "".

import path from "std:path"

print(path.extension(".bashrc"), path.stem(".bashrc"))   #  .bashrc
print(path.dirname("file.txt"), path.dirname("/file.txt"))   # . /

# Swap a file's extension.
fn with_extension(p: String, ext: String) -> String {
    path.join(path.dirname(p), path.stem(p) + ext)
}
print(with_extension("src/main.mh", ".mahc"))            # src/main.mahc

Normalizing

normalize(p) removes . segments and repeated separators and applies each .. to the segment before it. At a root, .. stays at the root. The result never has a trailing separator, and is "." when nothing is left:

import path from "std:path"

print(path.normalize("a/./b/../c//d/"))     # a/c/d
print(path.normalize("/../etc"))            # /etc
print(path.normalize("a/.."), path.normalize("../x"))   # . ../x
print(path.normalize("C:\\Users\\ann\\..\\bo"))          # C:/Users/bo

Relative paths

relative(from, to) is the path that leads from directory from to to. Both are normalized first. When they have different roots (or from climbs out further than to can follow), there is no relative path and the answer is to, normalized:

import path from "std:path"

print(path.relative("/a/b", "/a/c/d"))     # ../c/d
print(path.relative("src", "src/lib/x.mh"))   # lib/x.mh
print(path.relative("x", "x"))             # .
print(path.is_absolute("/etc"), path.is_absolute("C:\\x"), path.is_absolute("a/b"))   # true true false

Reference

Function
join(a, b)b after a with a separator; an absolute b replaces a
join_all(parts)join over a Vector, left to right
dirname(p)everything before the last segment ("." if none)
basename(p)the last segment ("" for a root)
extension(p)the last segment’s extension, from its last .
stem(p)the last segment without its extension
normalize(p)., .. and repeated separators resolved
is_absolute(p)starts with a separator, or a drive and a separator
relative(from, to)the path from directory from to to
Previous std:time Next std:json

Mah — ماه, "moon" in Persian. Built from scratch, pure Python (plus a Rust runtime).

Docs Stdlib Blog Changelog RSS GitHub