join(child: string) -- Модуль
- std.
path → - Получатель
- Path
- Минимальное число аргументов
- 1
- Максимальное число аргументов
- 1
Declaration and parameters
СсылкаДоступность
Включено по умолчанию · Не определено
Import std.path in language mode 5.21.
The current compiler selects std/path.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.
Получатель
Path
Ограничения параметров
Path.from(text) is the constructor for normalized relative paths and returns Result<Path, string>.
Path.from normalizes path separators and removes empty and dot components. Parent components must stay within the relative root. A path reduced to no components is represented by a dot.
Empty text, NUL, absolute paths, and parent traversal beyond the relative root return Err. These input failures are values that a caller can handle.
A leading slash or backslash returns Err. Text that starts with one ASCII character followed immediately by a colon returns Err.
Path.cwdRelative and Path.project are absent. A Path value already satisfies normalization and has no normalize member.
Path operations inspect text without accessing the filesystem. Constructing a Path does not establish that its target exists or is accessible.
Связанное правило · Construct normalized paths with Path.from →A Path is immutable normalized relative text. Every member evaluates its receiver and arguments once in ordinary call order. Members perform no host access and leave the receiver unchanged on success and failure.
to returns the exact normalized representation. Separators are forward slashes and the relative root is a dot. Constructing a Path from that text returns the same representation.
join accepts nonempty relative child text. It rejects NUL, a leading separator, and a colon immediately after one ASCII character before combining the child with the receiver. Both slash forms are separators. Parent components remove preceding components from the combined path and return Err when none remain to remove.
Joining a child may reach the relative root but may not cross it. A dot child preserves the receiver. Invalid child text returns Err containing an error string without producing a Path. Error text identifies Path.join and the invalid condition.
parent removes the final component. For a one component path it returns Some containing the dot root. The relative root has no parent and returns None().
file returns the final component without any preceding separator. The relative root returns None(). These results describe text and do not establish whether the path identifies a file or directory.
extension returns the text after the final dot in the file name, provided that dot is not its first character. A leading dot alone does not introduce an extension. A final dot returns Some(""). A name without such a dot and the relative root return None().
with replaces the final extension or appends one when it is absent. The argument supplies the suffix without a leading dot. An empty argument removes an existing suffix and its separating dot. A leading dot, either separator, or NUL in the argument returns Err.
with preserves a leading dot that belongs to the file name. It returns Err when the receiver is the relative root because that path has no file name. A successful replacement is normalized with the same rules as Path.from.
Path validation describes lexical text. Host operations may reject an otherwise valid Path because of platform naming rules, permissions, or capability restrictions. A Path does not establish filesystem existence or prevent a symbolic link from resolving elsewhere.
Связанное правило · Inspect and transform normalized paths →Результат
The declared result type is Result<Path, string>.
Эффекты
Ошибки
Result and effects
СсылкаJoin nonempty relative child text to this path and normalize the combined components. Invalid child text or traversal beyond the relative root returns Err.
Related entries
СсылкаConstruct normalized paths with Path.from
СсылкаConstruct normalized paths with Path.from
Path.from(text) is the constructor for normalized relative paths and returns Result<Path, string>.
Path.from normalizes path separators and removes empty and dot components. Parent components must stay within the relative root. A path reduced to no components is represented by a dot.
Empty text, NUL, absolute paths, and parent traversal beyond the relative root return Err. These input failures are values that a caller can handle.
A leading slash or backslash returns Err. Text that starts with one ASCII character followed immediately by a colon returns Err.
Path.cwdRelative and Path.project are absent. A Path value already satisfies normalization and has no normalize member.
Path operations inspect text without accessing the filesystem. Constructing a Path does not establish that its target exists or is accessible.
Причина
One constructor gives relative path text one interpretation. Normalization is a Path invariant, so a separate identity operation gives the same value a second spelling.
Construct a normalized path
Ссылкаimport std.path { Path }import std.testimport std.iolet chapter = test.assertOk(Path.from("chapters/./draft/../main.tpz"))io.writeLine(chapter.toString())
chapters/main.tpz
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
chapters/main.tpz
Reject a path that escapes its relative root
Ссылкаimport std.path { Path }import std.iomatch (Path.from("../chapter.tpz")) {case Err(_) => io.writeLine("outside root rejected")case Ok(_) => io.writeLine("accepted")}
outside root rejected
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
outside root rejected
Reject Path.cwdRelative
Ссылкаimport std.path { Path }let value = Path.cwdRelative("chapter.tpz")
Нет стандартного вывода.Ожидаемый результат
Ожидаемый результат
Этап отклонения check. Ненулевой код завершения.
stdlib-removed-member at
main.tpz:2:18
Reject Path.project
Ссылкаimport std.path { Path }let value = Path.project("chapter.tpz")
Нет стандартного вывода.Ожидаемый результат
Ожидаемый результат
Этап отклонения check. Ненулевой код завершения.
stdlib-removed-member at
main.tpz:2:18
Reject Path.normalize
Ссылкаimport std.path { Path }function inspect(path: Path) -> () {let value = path.normalize()return ()}
Нет стандартного вывода.Ожидаемый результат
Ожидаемый результат
Этап отклонения check. Ненулевой код завершения.
stdlib-removed-member at
main.tpz:3:20
Distinguish rejected ASCII prefixes from relative path text
Ссылкаimport std.path { Path }import std.testimport std.iotest.assertErr(Path.from("a:"))test.assertErr(Path.from("1:"))test.assertErr(Path.from("!:"))io.writeLine(test.assertOk(Path.from("aa:")).toString())io.writeLine(test.assertOk(Path.from("é:")).toString())io.writeLine(test.assertOk(Path.from("가:")).toString())
aa:
é:
가:
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
aa:é:가:
Diagnostics
СсылкаInspect and transform normalized paths
СсылкаInspect and transform normalized paths
A Path is immutable normalized relative text. Every member evaluates its receiver and arguments once in ordinary call order. Members perform no host access and leave the receiver unchanged on success and failure.
to returns the exact normalized representation. Separators are forward slashes and the relative root is a dot. Constructing a Path from that text returns the same representation.
join accepts nonempty relative child text. It rejects NUL, a leading separator, and a colon immediately after one ASCII character before combining the child with the receiver. Both slash forms are separators. Parent components remove preceding components from the combined path and return Err when none remain to remove.
Joining a child may reach the relative root but may not cross it. A dot child preserves the receiver. Invalid child text returns Err containing an error string without producing a Path. Error text identifies Path.join and the invalid condition.
parent removes the final component. For a one component path it returns Some containing the dot root. The relative root has no parent and returns None().
file returns the final component without any preceding separator. The relative root returns None(). These results describe text and do not establish whether the path identifies a file or directory.
extension returns the text after the final dot in the file name, provided that dot is not its first character. A leading dot alone does not introduce an extension. A final dot returns Some(""). A name without such a dot and the relative root return None().
with replaces the final extension or appends one when it is absent. The argument supplies the suffix without a leading dot. An empty argument removes an existing suffix and its separating dot. A leading dot, either separator, or NUL in the argument returns Err.
with preserves a leading dot that belongs to the file name. It returns Err when the receiver is the relative root because that path has no file name. A successful replacement is normalized with the same rules as Path.from.
Path validation describes lexical text. Host operations may reject an otherwise valid Path because of platform naming rules, permissions, or capability restrictions. A Path does not establish filesystem existence or prevent a symbolic link from resolving elsewhere.
Причина
One normalized representation makes composition predictable. Parent and extension queries describe components without consulting host state. A suffix has one accepted spelling, and joining validates the child before its leading separator can disappear inside the combined text.
Join relative components without changing the receiver
Ссылкаimport std.path { Path }import std.testimport std.iolet base = test.assertOk(Path.from("chapters/draft"))let child = test.assertOk(base.join("../final/./main.tpz"))io.writeLine(base.toString())io.writeLine(child.toString())io.writeLine(test.assertOk(base.join("../..")).toString())io.writeLine(test.assertOk(base.join(".")).toString())
chapters/draft
chapters/final/main.tpz
.
chapters/draft
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
chapters/draftchapters/final/main.tpz.chapters/draft
Reject invalid child text before joining
Ссылкаimport std.path { Path }import std.testimport std.iolet base = test.assertOk(Path.from("chapters"))for child in (["", "/outside", "C:/outside", "../../outside"]) {match (base.join(child)) {case Err(_) => io.writeLine("rejected")case Ok(_) => io.writeLine("accepted")}}io.writeLine(base.toString())
rejected
rejected
rejected
rejected
chapters
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
rejectedrejectedrejectedrejectedchapters
Inspect the final component and the relative root
Ссылкаimport std.path { Path }import std.testimport std.iolet file = test.assertOk(Path.from("chapters/main.tpz"))io.writeLine(test.assertSome(file.parent()).toString())io.writeLine(test.assertSome(file.fileName()))io.writeLine(test.assertSome(file.extension()))let root = test.assertOk(Path.from("."))test.assertNone(root.parent())test.assertNone(root.fileName())test.assertNone(root.extension())io.writeLine(root.toString())
chapters
main.tpz
tpz
.
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
chaptersmain.tpztpz.
Keep the relative root as the parent of one component
Ссылкаimport std.path { Path }import std.testimport std.iolet file = test.assertOk(Path.from("main.tpz"))match (file.parent()) {case Some(parent) => io.writeLine(parent.toString())case None() => io.writeLine("missing")}
.
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
.
Distinguish an absent extension from an empty extension
Ссылкаimport std.path { Path }import std.testimport std.iofor name in (["README", ".env", ".env.local", "archive.tar.gz", "trailing."]) {let file = test.assertOk(Path.from(name))match (file.extension()) {case Some(extension) => io.writeLine("present [{extension}]")case None() => io.writeLine("absent")}}
absent
absent
present [local]
present [gz]
present []
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
absentabsentpresent [local]present [gz]present []
Replace and remove a final extension
Ссылкаimport std.path { Path }import std.testimport std.iolet file = test.assertOk(Path.from("chapters/main.tpz"))io.writeLine(test.assertOk(file.withExtension("pdf")).toString())io.writeLine(test.assertOk(file.withExtension("")).toString())io.writeLine(file.toString())
chapters/main.pdf
chapters/main
chapters/main.tpz
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
chapters/main.pdfchapters/mainchapters/main.tpz
Preserve the name of a file that starts with a dot
Ссылкаimport std.path { Path }import std.testimport std.iolet file = test.assertOk(Path.from(".env"))io.writeLine(test.assertOk(file.withExtension("local")).toString())io.writeLine(test.assertOk(file.withExtension("")).toString())
.env.local
.env
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
.env.local.env
Reject a second suffix spelling and a path without a file name
Ссылкаimport std.path { Path }import std.testimport std.iolet file = test.assertOk(Path.from("chapter.txt"))for extension in ([".pdf", "pdf/extra", "pdf\\extra"]) {match (file.withExtension(extension)) {case Err(_) => io.writeLine("rejected")case Ok(_) => io.writeLine("accepted")}}let root = test.assertOk(Path.from("."))match (root.withExtension("pdf")) {case Err(_) => io.writeLine("root rejected")case Ok(_) => io.writeLine("root accepted")}
rejected
rejected
rejected
root rejected
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
rejectedrejectedrejectedroot rejected