Spec-Zone.ru › D

std.path

Этот модуль используется для обработки строк путей.

Все функции, за исключением expandTilde (и в некоторых случаях absolutePath и relativePath), являются функциями чистой обработки строк; они не зависят от какого-либо состояния вне программы, а также не выполняют реальных операций с файловой системой. Это означает, что модуль не различает путь к каталогу и путь к файлу, и не знает, существует ли объект, на который указывает путь, в файловой системе. Для различения этих случаев используйте std.file.isDir и std.file.exists.

Обратите внимание, что в Windows как обратный слэш (\) , так и прямой слэш (/) в принципе являются допустимыми разделителями каталогов. Этот модуль рассматривает их одинаково, но в случаях добавления нового разделителя будет использоваться обратный слэш. Кроме того, функция buildNormalizedPath заменит все слэши обратными слэшами на этой платформе.

В общем, функции этого модуля предполагают, что входные пути имеют правильный формат. (То есть, они не должны содержать недопустимых символов, должны соответствовать формату путей файловой системы и т.д.) Результат вызова функции для неправильного пути не определён. Когда существует вероятность того, что путь или имя файла неверны (например, когда они были введены пользователем), иногда желательно использовать функции isValidFilename и isValidPath для проверки этого.

Большинство функций не выполняют выделение памяти, и если возвращается строка, то обычно это фрагмент входной строки. Если функция выделяет память, это явно указано в документации.

Категория Функции
Нормализация absolutePath asAbsolutePath asNormalizedPath asRelativePath buildNormalizedPath buildPath chainPath expandTilde
Разбиение baseName dirName dirSeparator driveName pathSeparator pathSplitter relativePath rootName stripDrive
Валидация isAbsolute isDirSeparator isRooted isValidFilename isValidPath
Расширение defaultExtension extension setExtension stripExtension withDefaultExtension withExtension
Другие filenameCharCmp filenameCmp globMatch CaseSensitive

Авторы:
Lars Tandle Kyllingstad, Walter Bright, Grzegorz Adam Hankiewicz, Thomas Kühne, Andrei Alexandrescu
Лицензия:
Boost License 1.0
Исходный код
std/path.d
enum string dirSeparator;

Строка, используемая для разделения имён каталогов в пути. Под POSIX это косая черта, под Windows — обратная косая черта.

enum string pathSeparator;

Строка разделителя путей. Двоеточие под POSIX, точка с запятой под Windows.

pure nothrow @nogc @safe bool isDirSeparator(dchar c);

Определяет, является ли данный символ разделителем каталога.

В Windows это включает как \ , так и /. В POSIX это только /.

Примеры:
version (Windows)
{
    assert( '/'.isDirSeparator);
    assert( '\\'.isDirSeparator);
}
else
{
    assert( '/'.isDirSeparator);
    assert(!'\\'.isDirSeparator);
}
enum CaseSensitive: bool;

Этот enum используется в качестве шаблонного аргумента для функций, сравнивающих имена файлов, и определяет, является ли сравнение регистрозависимым или нет.

Примеры:
writeln(baseName!(CaseSensitive.no)("dir/file.EXT", ".ext")); // "file"
assert(baseName!(CaseSensitive.yes)("dir/file.EXT", ".ext") != "file");

version (Posix)
    writeln(relativePath!(CaseSensitive.no)("/FOO/bar", "/foo/baz")); // "../bar"
else
    writeln(relativePath!(CaseSensitive.no)(`c:\FOO\bar`, `c:\foo\baz`)); // `..\bar`
no

Имена файлов нечувствительны к регистру

yes

Имена файлов чувствительны к регистру

osDefault

Значение по умолчанию (или наиболее распространённое) для текущей платформы. То есть, no в Windows и Mac OS X, и yes во всех системах POSIX, кроме Darwin (Linux, *BSD и т. д.).

auto baseName(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && isSomeChar!(ElementType!R) && !isSomeString!R);

auto baseName(C)(C[] path)
Constraints: if (isSomeChar!C);

pure @safe inout(C)[] baseName(CaseSensitive cs = CaseSensitive.osDefault, C, C1)(inout(C)[] path, in C1[] suffix)
Constraints: if (isSomeChar!C && isSomeChar!C1);
Параметры:
cs Определяет, чувствительно ли к регистру сопоставление с суффиксом.
R path Имя пути. Может быть строкой или любым диапазоном символов с произвольным доступом.
C1[] suffix Необязательный суффикс, который необходимо удалить из имени файла.
Возвращаемое значение:
Имя файла в имени пути без ведущих каталогов и с необязательным отсечённым суффиксом. Если suffix указан, он будет сравниваться с path с использованием filenameCmp!cs, где cs — необязательный шаблонный параметр, определяющий, является ли сравнение регистрозависимым. Подробности см. в документации filenameCmp.
Примечание
Эта функция только удаляет указанный суффикс, который необязательно должен представлять расширение. Чтобы удалить расширение из пути независимо от того, что это за расширение, используйте stripExtension. Чтобы получить имя файла без ведущих каталогов и без расширения, объедините функции следующим образом: 
assert(baseName(stripExtension("dir/file.ext")) == "file");
Стандарты:
Эта функция соответствует требованиям POSIX для утилиты оболочки 'basename' с соответствующими адаптациями для путей Windows.
Примеры:
writeln(baseName("dir/file.ext")); // "file.ext"
writeln(baseName("dir/file.ext", ".ext")); // "file"
writeln(baseName("dir/file.ext", ".xyz")); // "file.ext"
writeln(baseName("dir/filename", "name")); // "file"
writeln(baseName("dir/subdir/")); // "subdir"

version (Windows)
{
    writeln(baseName(`d:file.ext`)); // "file.ext"
    writeln(baseName(`d:\dir\file.ext`)); // "file.ext"
}
auto dirName(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && isSomeChar!(ElementType!R) && !isSomeString!R);

auto dirName(C)(C[] path)
Constraints: if (isSomeChar!C);

Возвращает родительский каталог path. В Windows это включает букву диска, если она присутствует. Если path — это относительный путь, а родительский каталог — текущий рабочий каталог, возвращается ".".

Параметры:
R path Имя пути.
Возвращаемое значение:
Срез path или ".".
Стандарты:
Эта функция соответствует требованиям POSIX для утилиты оболочки 'dirname' с соответствующими адаптациями для путей Windows.
Примеры:
writeln(dirName("")); // "."
writeln(dirName("file"w)); // "."
writeln(dirName("dir/"d)); // "."
writeln(dirName("dir///")); // "."
writeln(dirName("dir/file"w.dup)); // "dir"
writeln(dirName("dir///file"d.dup)); // "dir"
writeln(dirName("dir/subdir/")); // "dir"
writeln(dirName("/dir/file"w)); // "/dir"
writeln(dirName("/file"d)); // "/"
writeln(dirName("/")); // "/"
writeln(dirName("///")); // "/"

version (Windows)
{
    writeln(dirName(`dir\`)); // `.`
    writeln(dirName(`dir\\\`)); // `.`
    writeln(dirName(`dir\file`)); // `dir`
    writeln(dirName(`dir\\\file`)); // `dir`
    writeln(dirName(`dir\subdir\`)); // `dir`
    writeln(dirName(`\dir\file`)); // `\dir`
    writeln(dirName(`\file`)); // `\`
    writeln(dirName(`\`)); // `\`
    writeln(dirName(`\\\`)); // `\`
    writeln(dirName(`d:`)); // `d:`
    writeln(dirName(`d:file`)); // `d:`
    writeln(dirName(`d:\`)); // `d:\`
    writeln(dirName(`d:\file`)); // `d:\`
    writeln(dirName(`d:\dir\file`)); // `d:\dir`
    writeln(dirName(`\\server\share\dir\file`)); // `\\server\share\dir`
    writeln(dirName(`\\server\share\file`)); // `\\server\share`
    writeln(dirName(`\\server\share\`)); // `\\server\share`
    writeln(dirName(`\\server\share`)); // `\\server\share`
}
auto rootName(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && isSomeChar!(ElementType!R) && !isSomeString!R);

auto rootName(C)(C[] path)
Constraints: if (isSomeChar!C);

Возвращает корневой каталог указанного пути или null , если путь не имеет корня.

Параметры:
R path Имя пути.
Возвращаемое значение:
Срез path.
Примеры:
assert(rootName("") is null);
assert(rootName("foo") is null);
writeln(rootName("/")); // "/"
writeln(rootName("/foo/bar")); // "/"

version (Windows)
{
    assert(rootName("d:foo") is null);
    writeln(rootName(`d:\foo`)); // `d:\`
    writeln(rootName(`\\server\share\foo`)); // `\\server\share`
    writeln(rootName(`\\server\share`)); // `\\server\share`
}
auto driveName(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && isSomeChar!(ElementType!R) && !isSomeString!R);

auto driveName(C)(C[] path)
Constraints: if (isSomeChar!C);

Получить часть диска пути.

Параметры:
R path строка или диапазон символов
Возвращаемое значение:
Срез path , представляющий диск, или пустой диапазон, если диск не указан. В случае UNC-путей возвращается сетевая общая папка. Всегда возвращает пустой диапазон в POSIX.
Примеры:
import std.range : empty;
version (Posix)  assert(driveName("c:/foo").empty);
version (Windows)
{
    assert(driveName(`dir\file`).empty);
    writeln(driveName(`d:file`)); // "d:"
    writeln(driveName(`d:\file`)); // "d:"
    writeln(driveName("d:")); // "d:"
    writeln(driveName(`\\server\share\file`)); // `\\server\share`
    writeln(driveName(`\\server\share\`)); // `\\server\share`
    writeln(driveName(`\\server\share`)); // `\\server\share`

    static assert(driveName(`d:\file`) == "d:");
}
auto stripDrive(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && isSomeChar!(ElementType!R) && !isSomeString!R);

auto stripDrive(C)(C[] path)
Constraints: if (isSomeChar!C);

Удаляет диск из пути Windows. В POSIX путь возвращается без изменений.

Параметры:
R path Путь
Возвращаемое значение:
Срез пути без компонента диска.
Примеры:
version (Windows)
{
    writeln(stripDrive(`d:\dir\file`)); // `\dir\file`
    writeln(stripDrive(`\\server\share\dir\file`)); // `\dir\file`
}
auto extension(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && isSomeChar!(ElementType!R) || is(StringTypeOf!R));
Параметры:
R path Имя пути.
Возвращаемое значение:
Часть расширения имени файла, включая точку. Если расширения нет, возвращается null.
Примеры:
import std.range : empty;
assert(extension("file").empty);
writeln(extension("file.")); // "."
writeln(extension("file.ext"w)); // ".ext"
writeln(extension("file.ext1.ext2"d)); // ".ext2"
assert(extension(".foo".dup).empty);
writeln(extension(".foo.ext"w.dup)); // ".ext"

static assert(extension("file").empty);
static assert(extension("file.ext") == ".ext");
auto stripExtension(R)(R path)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && isSomeChar!(ElementType!R) && !isSomeString!R);

auto stripExtension(C)(C[] path)
Constraints: if (isSomeChar!C);

Удаляет расширение из пути.

Параметры:
R path строка или диапазон для среза
Возвращаемое значение:
срез пути с удаленным расширением (если оно есть)
Примеры:
writeln(stripExtension("file")); // "file"
writeln(stripExtension("file.ext")); // "file"
writeln(stripExtension("file.ext1.ext2")); // "file.ext1"
writeln(stripExtension("file.")); // "file"
writeln(stripExtension(".file")); // ".file"
writeln(stripExtension(".file.ext")); // ".file"
writeln(stripExtension("dir/file.ext")); // "dir/file"
immutable(C1)[] setExtension(C1, C2)(in C1[] path, in C2[] ext)
Constraints: if (isSomeChar!C1 && !is(C1 == immutable) && is(immutable(C1) == immutable(C2)));

immutable(C1)[] setExtension(C1, C2)(immutable(C1)[] path, const(C2)[] ext)
Constraints: if (isSomeChar!C1 && is(immutable(C1) == immutable(C2)));

Устанавливает или заменяет расширение.

Если у имени файла уже есть расширение, оно заменяется. Если нет, расширение просто добавляется к имени файла. В ext включение ведущей точки необязательно.

Если расширение пустое, эта функция эквивалентна stripExtension.

Эта функция обычно выделяет новую строку (исключение может быть в случае, когда path неизменяемый и у него ещё нет расширения).

Параметры:
C1[] path Имя пути
C2[] ext Новое расширение
Возвращаемое значение:
Строка, содержащая путь из path, но где расширение изменено на ext.
См. также:
withExtension, который не выделяет память и возвращает ленивый диапазон.
Примеры:
writeln(setExtension("file", "ext")); // "file.ext"
writeln(setExtension("file"w, ".ext"w)); // "file.ext"
writeln(setExtension("file."d, "ext"d)); // "file.ext"
writeln(setExtension("file.", ".ext")); // "file.ext"
writeln(setExtension("file.old"w, "new"w)); // "file.new"
writeln(setExtension("file.old"d, ".new"d)); // "file.new"
auto withExtension(R, C)(R path, C[] ext)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && isSomeChar!(ElementType!R) && !isSomeString!R && isSomeChar!C);

auto withExtension(C1, C2)(C1[] path, C2[] ext)
Constraints: if (isSomeChar!C1 && isSomeChar!C2);

Замена существующего расширения файла на новое.

Параметры:
R path Строка или диапазон с произвольным доступом, представляющий имя файла
C[] ext новое расширение
Возвращаемое значение:
Диапазон с замещённым расширением path файла на ext. Тип элементов возвращаемого диапазона будет таким же, как и у path.
См. также:
setExtension
Примеры:
import std.array;
writeln(withExtension("file", "ext").array); // "file.ext"
writeln(withExtension("file"w, ".ext"w).array); // "file.ext"
writeln(withExtension("file.ext"w, ".").array); // "file."

import std.utf : byChar, byWchar;
writeln(withExtension("file".byChar, "ext").array); // "file.ext"
writeln(withExtension("file"w.byWchar, ".ext"w).array); // "file.ext"w
writeln(withExtension("file.ext"w.byWchar, ".").array); // "file."w
immutable(C1)[] defaultExtension(C1, C2)(in C1[] path, in C2[] ext)
Constraints: if (isSomeChar!C1 && is(immutable(C1) == immutable(C2)));
Параметры:
C1[] path Имя пути.
C2[] ext Используемое по умолчанию расширение.
Возвращает:
Путь, заданный path, с расширением, заданным ext, добавленным, если в пути его нет. Включение точки в расширении необязательно. Эта функция всегда выделяет новую строку, за исключением случая, когда path неизменяемый и уже имеет расширение.
Примеры:
writeln(defaultExtension("file", "ext")); // "file.ext"
writeln(defaultExtension("file", ".ext")); // "file.ext"
writeln(defaultExtension("file.", "ext")); // "file."
writeln(defaultExtension("file.old", "new")); // "file.old"
writeln(defaultExtension("file.old", ".new")); // "file.old"
auto withDefaultExtension(R, C)(R path, C[] ext)
Constraints: if (isRandomAccessRange!R && hasSlicing!R && hasLength!R && isSomeChar!(ElementType!R) && !isSomeString!R && isSomeChar!C);

auto withDefaultExtension(C1, C2)(C1[] path, C2[] ext)
Constraints: if (isSomeChar!C1 && isSomeChar!C2);

Установить расширение path на ext, если у path его нет.

Параметры:
R path путь как строка или диапазон
C[] ext расширение, может содержать ведущую точку
Возвращает:
диапазон с результатом
Примеры:
import std.array;
writeln(withDefaultExtension("file", "ext").array); // "file.ext"
writeln(withDefaultExtension("file"w, ".ext").array); // "file.ext"w
writeln(withDefaultExtension("file.", "ext").array); // "file."
writeln(withDefaultExtension("file", "").array); // "file."

import std.utf : byChar, byWchar;
writeln(withDefaultExtension("file".byChar, "ext").array); // "file.ext"
writeln(withDefaultExtension("file"w.byWchar, ".ext").array); // "file.ext"w
writeln(withDefaultExtension("file.".byChar, "ext"d).array); // "file."
writeln(withDefaultExtension("file".byChar, "").array); // "file."
immutable(ElementEncodingType!(ElementType!Range))[] buildPath(Range)(Range segments)
Constraints: if (isInputRange!Range && !isInfinite!Range && isSomeString!(ElementType!Range));

pure nothrow @safe immutable(C)[] buildPath(C)(const(C)[][] paths...)
Constraints: if (isSomeChar!C);

Объединяет один или несколько сегментов пути.

Эта функция принимает набор сегментов пути, заданных как входной диапазон элементов строк или как набор строковых аргументов, и конкатенирует их друг с другом. Разделители каталогов вставляются между сегментами при необходимости. Если какой-либо из сегментов пути является абсолютным (как определено в isAbsolute), предыдущие сегменты будут отброшены.

В Windows, если один из сегментов пути укоренён, но не абсолютный (например, \foo), все предыдущие сегменты пути до предыдущего корня будут отброшены. (См. пример ниже.)

Эта функция всегда выделяет память для хранения результирующего пути. Вариативная перегрузка гарантирует выполнение только одного выделения, так же, как и версия диапазона, если paths является диапазоном вперёд.

Параметры:
Range segments Входной диапазон сегментов для сборки пути.
Возвращает:
Собраный путь.
Примеры:
version (Posix)
{
    writeln(buildPath("foo", "bar", "baz")); // "foo/bar/baz"
    writeln(buildPath("/foo/", "bar/baz")); // "/foo/bar/baz"
    writeln(buildPath("/foo", "/bar")); // "/bar"
}

version (Windows)
{
    writeln(buildPath("foo", "bar", "baz")); // `foo\bar\baz`
    writeln(buildPath(`c:\foo`, `bar\baz`)); // `c:\foo\bar\baz`
    writeln(buildPath("foo", `d:\bar`)); // `d:\bar`
    writeln(buildPath("foo", `\bar`)); // `\bar`
    writeln(buildPath(`c:\foo`, `\bar`)); // `c:\bar`
}
auto chainPath(R1, R2, Ranges...)(R1 r1, R2 r2, Ranges ranges)
Constraints: if ((isRandomAccessRange!R1 && hasSlicing!R1 && hasLength!R1 && isSomeChar!(ElementType!R1) || isNarrowString!R1 && !isConvertibleToString!R1) && (isRandomAccessRange!R2 && hasSlicing!R2 && hasLength!R2 && isSomeChar!(ElementType!R2) || isNarrowString!R2 && !isConvertibleToString!R2) && (Ranges.length == 0 || is(typeof(chainPath(r2, ranges)))));

Конкатенирует сегменты пути для создания одного пути.

Параметры:
R1 r1 первый сегмент
R2 r2 второй сегмент
Ranges ranges 0 или более сегментов
Возвращает:
Ленивый диапазон, являющийся конкатенацией r1, r2 и диапазонов с разделителями путей. Тип результирующего элемента — тип элемента r1.
См. также:
buildPath
Примеры:
import std.array;
version (Posix)
{
    writeln(chainPath("foo", "bar", "baz").array); // "foo/bar/baz"
    writeln(chainPath("/foo/", "bar/baz").array); // "/foo/bar/baz"
    writeln(chainPath("/foo", "/bar").array); // "/bar"
}

version (Windows)
{
    writeln(chainPath("foo", "bar", "baz").array); // `foo\bar\baz`
    writeln(chainPath(`c:\foo`, `bar\baz`).array); // `c:\foo\bar\baz`
    writeln(chainPath("foo", `d:\bar`).array); // `d:\bar`
    writeln(chainPath("foo", `\bar`).array); // `\bar`
    writeln(chainPath(`c:\foo`, `\bar`).array); // `c:\bar`
}

import std.utf : byChar;
version (Posix)
{
    writeln(chainPath("foo", "bar", "baz").array); // "foo/bar/baz"
    writeln(chainPath("/foo/".byChar, "bar/baz").array); // "/foo/bar/baz"
    writeln(chainPath("/foo", "/bar".byChar).array); // "/bar"
}

version (Windows)
{
    writeln(chainPath("foo", "bar", "baz").array); // `foo\bar\baz`
    writeln(chainPath(`c:\foo`.byChar, `bar\baz`).array); // `c:\foo\bar\baz`
    writeln(chainPath("foo", `d:\bar`).array); // `d:\bar`
    writeln(chainPath("foo", `\bar`.byChar).array); // `\bar`
    writeln(chainPath(`c:\foo`, `\bar`w).array); // `c:\bar`
}
pure nothrow @safe immutable(C)[] buildNormalizedPath(C)(const(C[])[] paths...)
Constraints: if (isSomeChar!C);

Выполняет ту же задачу, что и buildPath, одновременно разрешая символы текущей/родительской директории ("." и "..") и удаляя избыточные разделители каталогов. Вернёт "." если путь ведёт к начальной директории. В Windows слэши заменяются бэкслэшами.

Использование buildNormalizedPath для пустых путей всегда вернёт null.

Обратите внимание, что эта функция не разрешает символические ссылки.

Эта функция всегда выделяет память для хранения результирующего пути. Используйте asNormalizedPath для избежания выделения памяти.

Параметры:
const(C[])[] paths Массив путей для сборки.
Возвращает:
Собраный путь.
Примеры:
writeln(buildNormalizedPath("foo", "..")); // "."

version (Posix)
{
    writeln(buildNormalizedPath("/foo/./bar/..//baz/")); // "/foo/baz"
    writeln(buildNormalizedPath("../foo/.")); // "../foo"
    writeln(buildNormalizedPath("/foo", "bar/baz/")); // "/foo/bar/baz"
    writeln(buildNormalizedPath("/foo", "/bar/..", "baz")); // "/baz"
    writeln(buildNormalizedPath("foo/./bar", "../../", "../baz")); // "../baz"
    writeln(buildNormalizedPath("/foo/./bar", "../../baz")); // "/baz"
}

version (Windows)
{
    writeln(buildNormalizedPath(`c:\foo\.\bar/..\\baz\`)); // `c:\foo\baz`
    writeln(buildNormalizedPath(`..\foo\.`)); // `..\foo`
    writeln(buildNormalizedPath(`c:\foo`, `bar\baz\`)); // `c:\foo\bar\baz`
    writeln(buildNormalizedPath(`c:\foo`, `bar/..`)); // `c:\foo`
    assert(buildNormalizedPath(`\\server\share\foo`, `..\bar`) ==
            `\\server\share\bar`);
}
auto asNormalizedPath(R)(R path)
Constraints: if (isSomeChar!(ElementEncodingType!R) && (isRandomAccessRange!R && hasSlicing!R && hasLength!R || isNarrowString!R) && !isConvertibleToString!R);

Нормализует путь, разрешая символы текущей/родительской директории ("." и "..") и удаляя избыточные разделители каталогов. Вернёт "." если путь ведёт к начальной директории. В Windows слэши заменяются бэкслэшами.

Использование asNormalizedPath для пустых путей всегда вернёт пустой путь.

Не разрешает символические ссылки.

Эта функция всегда выделяет память для хранения результирующего пути. Используйте buildNormalizedPath для выделения памяти и возврата строки.

Параметры:
R path строка или диапазон с произвольным доступом, представляющий путь для нормализации
Возвращает:
нормализованный путь как диапазон вперёд
Примеры:
import std.array;
writeln(asNormalizedPath("foo/..").array); // "."

version (Posix)
{
    writeln(asNormalizedPath("/foo/./bar/..//baz/").array); // "/foo/baz"
    writeln(asNormalizedPath("../foo/.").array); // "../foo"
    writeln(asNormalizedPath("/foo/bar/baz/").array); // "/foo/bar/baz"
    writeln(asNormalizedPath("/foo/./bar/../../baz").array); // "/baz"
}

version (Windows)
{
    writeln(asNormalizedPath(`c:\foo\.\bar/..\\baz\`).array); // `c:\foo\baz`
    writeln(asNormalizedPath(`..\foo\.`).array); // `..\foo`
    writeln(asNormalizedPath(`c:\foo\bar\baz\`).array); // `c:\foo\bar\baz`
    writeln(asNormalizedPath(`c:\foo\bar/..`).array); // `c:\foo`
    assert(asNormalizedPath(`\\server\share\foo\..\bar`).array ==
            `\\server\share\bar`);
}
auto pathSplitter(R)(R path)
Constraints: if ((isRandomAccessRange!R && hasSlicing!R || isNarrowString!R) && !isConvertibleToString!R);

Разбивает путь на его элементы.

Параметры:
R path строка или разрезаемый диапазон с произвольным доступом
Возвращает:
двунаправленный диапазон фрагментов path
Примеры:
import std.algorithm.comparison : equal;
import std.conv : to;

assert(equal(pathSplitter("/"), ["/"]));
assert(equal(pathSplitter("/foo/bar"), ["/", "foo", "bar"]));
assert(equal(pathSplitter("foo/../bar//./"), ["foo", "..", "bar", "."]));

version (Posix)
{
    assert(equal(pathSplitter("//foo/bar"), ["/", "foo", "bar"]));
}

version (Windows)
{
    assert(equal(pathSplitter(`foo\..\bar\/.\`), ["foo", "..", "bar", "."]));
    assert(equal(pathSplitter("c:"), ["c:"]));
    assert(equal(pathSplitter(`c:\foo\bar`), [`c:\`, "foo", "bar"]));
    assert(equal(pathSplitter(`c:foo\bar`), ["c:foo", "bar"]));
}
bool isRooted(R)(R path)
Constraints: if (isRandomAccessRange!R && isSomeChar!(ElementType!R) || is(StringTypeOf!R));

Определяет, начинается ли путь в корневой директории.

Параметры:
R path Имя пути.
Возвращает:
Начинается ли путь в корневой директории. В POSIX эта функция возвращает true тогда и только тогда, когда путь начинается с слэша (/). В Windows эта функция возвращает true, если путь начинается в корневой директории текущего диска, какого-либо другого диска или сетевого диска.
Примеры:
version (Posix)
{
    assert( isRooted("/"));
    assert( isRooted("/foo"));
    assert(!isRooted("foo"));
    assert(!isRooted("../foo"));
}

version (Windows)
{
    assert( isRooted(`\`));
    assert( isRooted(`\foo`));
    assert( isRooted(`d:\foo`));
    assert( isRooted(`\\foo\bar`));
    assert(!isRooted("foo"));
    assert(!isRooted("d:foo"));
}
pure nothrow @safe bool isAbsolute(R)(R path)
Constraints: if (isRandomAccessRange!R && isSomeChar!(ElementType!R) || is(StringTypeOf!R));

Определяет, является ли путь абсолютным или нет.

Параметры:
R path Имя пути.
Возвращает:
Является ли путь абсолютным или нет.
Пример
В POSIX абсолютный путь начинается в корневой директории. (Фактически, _isAbsolute это просто псевдоним для isRooted.) 
version (Posix)
{
    assert(isAbsolute("/"));
    assert(isAbsolute("/foo"));
    assert(!isAbsolute("foo"));
    assert(!isAbsolute("../foo"));
}
В Windows абсолютный путь начинается в корневой директории конкретного диска. Следовательно, он должен начинаться с d:\ или d:/, где d - буква диска. В качестве альтернативы, это может быть сетевой путь, т.е. путь, начинающийся с двух (обратных) слэшей. 
version (Windows)
{
    assert(isAbsolute(`d:\`));
    assert(isAbsolute(`d:\foo`));
    assert(isAbsolute(`\\foo\bar`));
    assert(!isAbsolute(`\`));
    assert(!isAbsolute(`\foo`));
    assert(!isAbsolute("d:foo"));
}
pure @safe string absolutePath(string path, lazy string base = getcwd());

Преобразует path в абсолютный путь.

Используется следующий алгоритм:

  1. Если path пустая, вернуть null.
  2. Если path уже абсолютная, вернуть её.
  3. В противном случае, добавить path к base и вернуть результат. Если base не указано, используется текущая рабочая директория.
Функция выделяет память только в том случае, если она доходит до третьей стадии этого алгоритма.

Параметры:
string path относительный путь для преобразования
string base базовая директория относительного пути
Возвращает:
строка преобразованного пути
Выбрасывает:
Exception если указанная базовая директория не абсолютная.
См. также:
asAbsolutePath который не выделяет
Примеры:
version (Posix)
{
    writeln(absolutePath("some/file", "/foo/bar")); // "/foo/bar/some/file"
    writeln(absolutePath("../file", "/foo/bar")); // "/foo/bar/../file"
    writeln(absolutePath("/some/file", "/foo/bar")); // "/some/file"
}

version (Windows)
{
    writeln(absolutePath(`some\file`, `c:\foo\bar`)); // `c:\foo\bar\some\file`
    writeln(absolutePath(`..\file`, `c:\foo\bar`)); // `c:\foo\bar\..\file`
    writeln(absolutePath(`c:\some\file`, `c:\foo\bar`)); // `c:\some\file`
    writeln(absolutePath(`\`, `c:\`)); // `c:\`
    writeln(absolutePath(`\some\file`, `c:\foo\bar`)); // `c:\some\file`
}
auto asAbsolutePath(R)(R path)
Constraints: if ((isRandomAccessRange!R && isSomeChar!(ElementType!R) || isNarrowString!R) && !isConvertibleToString!R);

Преобразует path в абсолютный путь.

Используется следующий алгоритм:

  1. Если path пусто, вернуть null.
  2. Если path уже абсолютный, вернуть его.
  3. В противном случае добавить path к текущему рабочему каталогу, что выделяет память.

Параметры:
R path относительный путь для преобразования
Возвращает:
преобразованный путь в виде ленивого диапазона
См. также:
absolutePath которая возвращает выделенную строку
Примеры:
import std.array;
writeln(asAbsolutePath(cast(string)null).array); // ""
version (Posix)
{
    writeln(asAbsolutePath("/foo").array); // "/foo"
}
version (Windows)
{
    writeln(asAbsolutePath("c:/foo").array); // "c:/foo"
}
asAbsolutePath("foo");
string relativePath(CaseSensitive cs = CaseSensitive.osDefault)(string path, lazy string base = getcwd());

Преобразует path в относительный путь.

Возвращаемый путь является относительным к base, который по умолчанию является текущим рабочим каталогом. Если указан, base должен быть абсолютным путем, и всегда предполагается, что он ссылается на каталог. Если path и base ссылаются на один и тот же каталог, функция возвращает ..

Используется следующий алгоритм:

  1. Если path — это относительный каталог, вернуть его без изменений.
  2. Найти общий корень между path и base.. Если общего корня нет, вернуть path без изменений.
  3. Подготовить строку с необходимым числом ../ или ..\ для достижения общего корня из базового пути.
  4. Добавить оставшиеся сегменты path к строке и вернуть ее.


На втором шаге компоненты пути сравниваются с использованием filenameCmp!cs, где cs является необязательным параметром шаблона, определяющим, является ли сравнение чувствительным к регистру или нет. Подробности см. в документации filenameCmp.

Эта функция выделяет память.

Параметры:
cs Является ли сопоставление имён компонентов пути с базовым путём чувствительным к регистру.
string path Имя пути.
string base Базовый путь для построения относительного пути.
Возвращает:
Относительный путь.
См. также:
asRelativePath, которая не выделяет память
Исключения:
Exception если указанный базовый каталог не является абсолютным.
Примеры:
writeln(relativePath("foo")); // "foo"

version (Posix)
{
    writeln(relativePath("foo", "/bar")); // "foo"
    writeln(relativePath("/foo/bar", "/foo/bar")); // "."
    writeln(relativePath("/foo/bar", "/foo/baz")); // "../bar"
    writeln(relativePath("/foo/bar/baz", "/foo/woo/wee")); // "../../bar/baz"
    writeln(relativePath("/foo/bar/baz", "/foo/bar")); // "baz"
}
version (Windows)
{
    writeln(relativePath("foo", `c:\bar`)); // "foo"
    writeln(relativePath(`c:\foo\bar`, `c:\foo\bar`)); // "."
    writeln(relativePath(`c:\foo\bar`, `c:\foo\baz`)); // `..\bar`
    writeln(relativePath(`c:\foo\bar\baz`, `c:\foo\woo\wee`)); // `..\..\bar\baz`
    writeln(relativePath(`c:\foo\bar\baz`, `c:\foo\bar`)); // "baz"
    writeln(relativePath(`c:\foo\bar`, `d:\foo`)); // `c:\foo\bar`
}
auto asRelativePath(CaseSensitive cs = CaseSensitive.osDefault, R1, R2)(R1 path, R2 base)
Constraints: if ((isNarrowString!R1 || isRandomAccessRange!R1 && hasSlicing!R1 && isSomeChar!(ElementType!R1) && !isConvertibleToString!R1) && (isNarrowString!R2 || isRandomAccessRange!R2 && hasSlicing!R2 && isSomeChar!(ElementType!R2) && !isConvertibleToString!R2));

Преобразует path в путь, относительный к base.

Возвращаемый путь является относительным к base, который обычно является текущим рабочим каталогом. base должен быть абсолютным путем, и всегда предполагается, что он ссылается на каталог. Если path и base ссылаются на один и тот же каталог, функция возвращает '.'.

Используется следующий алгоритм:

  1. Если path — это относительный каталог, вернуть его без изменений.
  2. Найти общий корень между path и base.. Если общего корня нет, вернуть path без изменений.
  3. Подготовить строку с необходимым числом ../ или ..\ для достижения общего корня из базового пути.
  4. Добавить оставшиеся сегменты path к строке и вернуть ее.


На втором шаге компоненты пути сравниваются с использованием filenameCmp!cs, где cs — необязательный параметр шаблона, определяющий, является ли сравнение чувствительным к регистру или нет. Подробности см. в документации filenameCmp.

Параметры:
R1 path путь для преобразования
R2 base абсолютный путь
cs чувствительность сравнения имён файлов; по умолчанию CaseSensitive.osDefault
Возвращает:
случайный доступный диапазон преобразованного пути
См. также:
relativePath
Примеры:
import std.array;
version (Posix)
{
    writeln(asRelativePath("foo", "/bar").array); // "foo"
    writeln(asRelativePath("/foo/bar", "/foo/bar").array); // "."
    writeln(asRelativePath("/foo/bar", "/foo/baz").array); // "../bar"
    writeln(asRelativePath("/foo/bar/baz", "/foo/woo/wee").array); // "../../bar/baz"
    writeln(asRelativePath("/foo/bar/baz", "/foo/bar").array); // "baz"
}
else version (Windows)
{
    writeln(asRelativePath("foo", `c:\bar`).array); // "foo"
    writeln(asRelativePath(`c:\foo\bar`, `c:\foo\bar`).array); // "."
    writeln(asRelativePath(`c:\foo\bar`, `c:\foo\baz`).array); // `..\bar`
    writeln(asRelativePath(`c:\foo\bar\baz`, `c:\foo\woo\wee`).array); // `..\..\bar\baz`
    writeln(asRelativePath(`c:/foo/bar/baz`, `c:\foo\woo\wee`).array); // `..\..\bar\baz`
    writeln(asRelativePath(`c:\foo\bar\baz`, `c:\foo\bar`).array); // "baz"
    writeln(asRelativePath(`c:\foo\bar`, `d:\foo`).array); // `c:\foo\bar`
    writeln(asRelativePath(`\\foo\bar`, `c:\foo`).array); // `\\foo\bar`
}
else
    static assert(0);
pure nothrow @safe int filenameCharCmp(CaseSensitive cs = CaseSensitive.osDefault)(dchar a, dchar b);

Сравнивает символы имени файла.

Эта функция может выполнять сравнение, чувствительное или нечувствительное к регистру. Это контролируется параметром шаблона cs, который, если не указан, задаётся значением CaseSensitive.osDefault.

В Windows символы обратного слэша и слэша (\ и /) считаются равными.

Параметры:
cs Чувствительность к регистру сравнения.
dchar a Символ имени файла.
dchar b Символ имени файла.
Возвращает:
< 0 если a < b, 0 если a == b, и > 0 если a > b.
Примеры:
writeln(filenameCharCmp('a', 'a')); // 0
assert(filenameCharCmp('a', 'b') < 0);
assert(filenameCharCmp('b', 'a') > 0);

version (linux)
{
    // Same as calling filenameCharCmp!(CaseSensitive.yes)(a, b)
    assert(filenameCharCmp('A', 'a') < 0);
    assert(filenameCharCmp('a', 'A') > 0);
}
version (Windows)
{
    // Same as calling filenameCharCmp!(CaseSensitive.no)(a, b)
    writeln(filenameCharCmp('a', 'A')); // 0
    assert(filenameCharCmp('a', 'B') < 0);
    assert(filenameCharCmp('A', 'b') < 0);
}
int filenameCmp(CaseSensitive cs = CaseSensitive.osDefault, Range1, Range2)(Range1 filename1, Range2 filename2)
Constraints: if (isInputRange!Range1 && !isInfinite!Range1 && isSomeChar!(ElementEncodingType!Range1) && !isConvertibleToString!Range1 && isInputRange!Range2 && !isInfinite!Range2 && isSomeChar!(ElementEncodingType!Range2) && !isConvertibleToString!Range2);

Сравнивает имена файлов и возвращает

Индивидуальные символы сравниваются с помощью filenameCharCmp!cs, где cs является необязательным параметром шаблона, определяющим, является ли сравнение чувствительным к регистру или нет.

Обработка недопустимых кодировок UTF определяется реализацией.

Параметры:
cs чувствительность к регистру
Range1 filename1 диапазон для первого имени файла
Range2 filename2 диапазон для второго имени файла
Возвращает:
< 0 если filename1 < filename2, 0 если filename1 == filename2 и > 0 если filename1 > filename2.
См. также:
filenameCharCmp
Примеры:
writeln(filenameCmp("abc", "abc")); // 0
assert(filenameCmp("abc", "abd") < 0);
assert(filenameCmp("abc", "abb") > 0);
assert(filenameCmp("abc", "abcd") < 0);
assert(filenameCmp("abcd", "abc") > 0);

version (linux)
{
    // Same as calling filenameCmp!(CaseSensitive.yes)(filename1, filename2)
    assert(filenameCmp("Abc", "abc") < 0);
    assert(filenameCmp("abc", "Abc") > 0);
}
version (Windows)
{
    // Same as calling filenameCmp!(CaseSensitive.no)(filename1, filename2)
    writeln(filenameCmp("Abc", "abc")); // 0
    writeln(filenameCmp("abc", "Abc")); // 0
    assert(filenameCmp("Abc", "abD") < 0);
    assert(filenameCmp("abc", "AbB") > 0);
}
pure nothrow @safe bool globMatch(CaseSensitive cs = CaseSensitive.osDefault, C, Range)(Range path, const(C)[] pattern)
Constraints: if (isForwardRange!Range && !isInfinite!Range && isSomeChar!(ElementEncodingType!Range) && !isConvertibleToString!Range && isSomeChar!C && is(immutable(C) == immutable(ElementEncodingType!Range)));

Сопоставляет шаблон с путём.

Некоторые символы шаблона имеют специальное значение (они являются метасимволами) и не могут быть экранированы. Это:

* Сопоставляет 0 или более вхождений любого символа.
? Сопоставляет ровно одно вхождение любого символа.
[chars] Сопоставляет одно вхождение любого символа, присутствующего в скобках.
[!chars] Сопоставляет одно вхождение любого символа, отсутствующего в скобках после восклицательного знака.
{string1,string2,…} Сопоставляет любой из указанных строк.


Индивидуальные символы сравниваются с помощью filenameCharCmp!cs, где cs — необязательный параметр шаблона, определяющий, является ли сравнение чувствительным к регистру или нет. Подробности см. в документации filenameCharCmp.

Обратите внимание, что символы разделителей каталогов и точки не препятствуют сопоставлению метасимвола с последующими частями пути.

Параметры:
cs Является ли сопоставление чувствительным к регистру
Range path Путь для сопоставления
const(C)[] pattern Шаблон glob
Возвращает:
true если шаблон соответствует пути, false в противном случае.
См. также:
Wikipedia: glob (программирование)
Примеры:
assert(globMatch("foo.bar", "*"));
assert(globMatch("foo.bar", "*.*"));
assert(globMatch(`foo/foo\bar`, "f*b*r"));
assert(globMatch("foo.bar", "f???bar"));
assert(globMatch("foo.bar", "[fg]???bar"));
assert(globMatch("foo.bar", "[!gh]*bar"));
assert(globMatch("bar.fooz", "bar.{foo,bif}z"));
assert(globMatch("bar.bifz", "bar.{foo,bif}z"));

version (Windows)
{
    // Same as calling globMatch!(CaseSensitive.no)(path, pattern)
    assert(globMatch("foo", "Foo"));
    assert(globMatch("Goo.bar", "[fg]???bar"));
}
version (linux)
{
    // Same as calling globMatch!(CaseSensitive.yes)(path, pattern)
    assert(!globMatch("foo", "Foo"));
    assert(!globMatch("Goo.bar", "[fg]???bar"));
}
bool isValidFilename(Range)(Range filename)
Constraints: if ((isRandomAccessRange!Range && hasLength!Range && hasSlicing!Range && isSomeChar!(ElementEncodingType!Range) || isNarrowString!Range) && !isConvertibleToString!Range);

Проверяет, является ли заданное имя файла или каталога допустимым.

Максимальная длина filename задаётся константой core.stdc.stdio.FILENAME_MAX. (В Windows это число определено как максимальное количество точек кода UTF-16, и тест будет давать строго правильные результаты только тогда, когда filename является строкой из wchar.)

В Windows должны быть соблюдены следующие критерии (источник):

  • filename не должно содержать символов, целые представления которых находятся в диапазоне от 0 до 31.
  • filename не должно содержать следующих зарезервированных символов: <>:"/\|?*
  • filename не может заканчиваться пробелом (' ') или точкой ('.').


В POSIX filename не может содержать обратную косую черту ('/') или нулевой символ ('\0').

Параметры:
Диапазон filename строка для проверки
Возвращает:
true тогда и только тогда, когда filename не пуста, не слишком длинна и не содержит недопустимых символов.
Примеры:
import std.utf : byCodeUnit;

assert(isValidFilename("hello.exe".byCodeUnit));
bool isValidPath(Range)(Range path)
Constraints: if ((isRandomAccessRange!Range && hasLength!Range && hasSlicing!Range && isSomeChar!(ElementEncodingType!Range) || isNarrowString!Range) && !isConvertibleToString!Range);

Проверяет, является ли path допустимым путем.

В общем случае эта функция проверяет, что path не пуста и что каждый компонент пути либо удовлетворяет isValidFilename, либо равен "." или "..".

Она не проверяет, указывает ли путь на существующий файл или каталог; для этой цели используйте std.file.exists.

В Windows применяются некоторые специальные правила:

  • Если второй символ path является двоеточием (':'), первый символ интерпретируется как буква диска и должен быть в диапазоне A-Z (регистронезависимо).
  • Если path имеет вид \\server\share\... (UNC-путь), isValidFilename применяется к серверу и обмену.
  • Если path начинается с \\?\ (длинный UNC-путь), единственное требование к остальной части строки заключается в том, чтобы она не содержала нулевого символа.
  • Если path начинается с \\.\ (пространство имён устройств Win32), эта функция возвращает false; такие пути выходят за рамки этого модуля.

Параметры:
Диапазон path строка или диапазон символов для проверки
Возвращает:
true, если path является допустимым путем.
Примеры:
assert(isValidPath("/foo/bar"));
assert(!isValidPath("/foo\0/bar"));
assert(isValidPath("/"));
assert(isValidPath("a"));

version (Windows)
{
    assert(isValidPath(`c:\`));
    assert(isValidPath(`c:\foo`));
    assert(isValidPath(`c:\foo\.\bar\\\..\`));
    assert(!isValidPath(`!:\foo`));
    assert(!isValidPath(`c::\foo`));
    assert(!isValidPath(`c:\foo?`));
    assert(!isValidPath(`c:\foo.`));

    assert(isValidPath(`\\server\share`));
    assert(isValidPath(`\\server\share\foo`));
    assert(isValidPath(`\\server\share\\foo`));
    assert(!isValidPath(`\\\server\share\foo`));
    assert(!isValidPath(`\\server\\share\foo`));
    assert(!isValidPath(`\\ser*er\share\foo`));
    assert(!isValidPath(`\\server\sha?e\foo`));
    assert(!isValidPath(`\\server\share\|oo`));

    assert(isValidPath(`\\?\<>:"?*|/\..\.`));
    assert(!isValidPath("\\\\?\\foo\0bar"));

    assert(!isValidPath(`\\.\PhysicalDisk1`));
    assert(!isValidPath(`\\`));
}

import std.utf : byCodeUnit;
assert(isValidPath("/foo/bar".byCodeUnit));
nothrow @safe string expandTilde(string inputPath);

Выполняет расширение тильды в путях на системах POSIX. В Windows эта функция ничего не делает.

Существует два способа использования расширения тильды в пути. Один заключается в использовании тильды или тильды, за которой следует разделитель путей. В этом случае тильда будет расширена значением переменной окружения HOME. Второй способ заключается в добавлении имени пользователя после тильды (т.е. ~john/Mail). В этом случае имя пользователя будет искаться в базе данных пользователей (т.е. /etc/passwd в системах Unix) и расширится до соответствующего пути. Имя пользователя рассматривается как строка после тильды, заканчивающаяся в первом вхождении разделителя путей.

Обратите внимание, что использование синтаксиса ~user может давать разные значения, чем просто ~, если переменная окружения не соответствует значению, хранящемуся в базе данных пользователей.

При использовании версии переменной окружения путь не будет изменён, если переменная окружения не существует или пуста. При использовании версии базы данных путь не будет изменён, если пользователя нет в базе данных или не хватает памяти для выполнения запроса.

Эта функция выполняет несколько операций выделения памяти.

Параметры:
строка inputPath имя пути для расширения.
Возвращает:
inputPath с расширенной тильдой или просто inputPath, если расширение невозможно. Для Windows expandTilde просто возвращает свой аргумент inputPath.
Пример
void processFile(string path)
{
    // Allow calling this function with paths such as ~/foo
    auto fullPath = expandTilde(path);
    ...
}
Примеры:
version (Posix)
{
    import std.process : environment;

    auto oldHome = environment["HOME"];
    scope(exit) environment["HOME"] = oldHome;

    environment["HOME"] = "dmd/test";
    writeln(expandTilde("~/")); // "dmd/test/"
    writeln(expandTilde("~")); // "dmd/test"
}

© 1999–2021 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_path.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API