std.path

This module is used to manipulate path strings.

All functions, with the exception of expandTilde (and in some cases absolutePath and relativePath), are pure string manipulation functions; they don't depend on any state outside the program, nor do they perform any actual file system actions. This has the consequence that the module does not make any distinction between a path that points to a directory and a path that points to a file, and it does not know whether or not the object pointed to by the path actually exists in the file system. To differentiate between these cases, use isDir and

exists.

Note that on Windows, both the backslash (`\`) and the slash (`/`) are in principle valid directory separators. This module treats them both on equal footing, but in cases where a new separator is added, a backslash will be used. Furthermore, the buildNormalizedPath function will replace all slashes with backslashes on that platform.

In general, the functions in this module assume that the input paths are well-formed. (That is, they should not contain invalid characters, they should follow the file system's path format, etc.) The result of calling a function on an ill-formed path is undefined. When there is a chance that a path or a file name is invalid (for instance, when it has been input by the user), it may sometimes be desirable to use the

isValidFilename and isValidPath functions to check

this.

Most functions do not perform any memory allocations, and if a string is returned, it is usually a slice of an input string. If a function allocates, this is explicitly mentioned in the documentation.

Authors

Lars Tandle Kyllingstad, Walter Bright,

Grzegorz Adam Hankiewicz, Thomas Kühne,

Andrei Alexandrescu

Copyright

License

Boost License 1.0

Source:

std/path.d

tmpl BaseOf

enum CaseSensitive

fn _baseName _dirName _driveName _rootName _stripDrive _stripExtension _withDefaultExtension _withExtension absolutePath asAbsolutePath asNormalizedPath asRelativePath baseName buildNormalizedPath buildPath chainPath defaultExtension dirName driveName expandTilde extension extSeparatorPos filenameCharCmp filenameCmp globMatch isDirSeparator isDriveSeparator isRooted isValidFilename isValidPath lastSeparator ltrimDirSeparators pathSplitter relativePath rootName rtrimDirSeparators setExtension stripDrive stripExtension trimDirSeparators withDefaultExtension withExtension

Types 1

enumCaseSensitive : bool

This enum is used as a template argument to functions which compare file names, and determines whether the comparison is case sensitive or not.

no = falseFile names are case insensitive

yes = trueFile names are case sensitive

osDefault = osDefaultCaseSensitivityThe default (or most common) setting for the current platform. That is, `no` on Windows and Mac OS X, and `yes` on all POSIX systems except Darwin (Linux, *BSD, etc.).

Functions 62

fnbool isDirSeparator(dchar c) @safe pure nothrow @nogcDetermines whether the given character is a directory separator.

private fnbool isDriveSeparator(dchar c) @safe pure nothrow @nogc

private fn

ptrdiff_t lastSeparator(R)(R path) if (isRandomAccessRange!R &&  isSomeChar!(ElementType!R)  ||
     isNarrowString!R)

private fnauto ltrimDirSeparators(R)(R path) if (isSomeFiniteCharInputRange!R || isNarrowString!R)

private fn

auto rtrimDirSeparators(R)(R path) if (isBidirectionalRange!R &&  isSomeChar!(ElementType!R)  ||
     isNarrowString!R)

private fn

auto trimDirSeparators(R)(R path) if (isBidirectionalRange!R &&  isSomeChar!(ElementType!R)  ||
     isNarrowString!R)

auto baseName(R)(return  scope  R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  isSomeChar!(ElementType!R)  && !isSomeString!R)

Params: cs = Whether or not suffix matching is case-sensitive. path = A path name. It can be a string, or any random-access range of characters. suffix = An optional suffix to be removed from the f...

fnauto baseName(C)(return scope C[] path) if (isSomeChar!C)ditto

inout(C)[] baseName(CaseSensitive cs =  CaseSensitive.osDefault,  C,  C1)(return  scope  inout(C)[]  path,  in  C1[]  suffix) if (isSomeChar!C &&  isSomeChar!C1)

@safe pureditto

private fn

R _baseName(R)(return  scope  R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  isSomeChar!(ElementType!R)  ||  isNarrowString!R)

auto dirName(R)(return  scope  R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  && !isSomeString!R)

Returns the parent directory of `path`. On Windows, this includes the drive letter if present. If `path` is a relative path and the parent directory is the current working directory, returns `"."`.

fnauto dirName(C)(return scope C[] path) if (isSomeChar!C)ditto

private fnauto _dirName(R)(return scope R path)

auto rootName(R)(R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  && !isSomeString!R)

Returns the root directory of the specified path, or `null` if the path is not rooted.

fnauto rootName(C)(C[] path) if (isSomeChar!C)ditto

private fnauto _rootName(R)(R path)

auto driveName(R)(R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  && !isSomeString!R)

Get the drive portion of a path.

fnauto driveName(C)(C[] path) if (isSomeChar!C)ditto

private fnauto _driveName(R)(R path)

auto stripDrive(R)(R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  isSomeChar!(ElementType!R)  && !isSomeString!R)

Strips the drive from a Windows path. On POSIX, the path is returned unaltered.

fnauto stripDrive(C)(C[] path) if (isSomeChar!C)ditto

private fnauto _stripDrive(R)(R path)

private fn

ptrdiff_t extSeparatorPos(R)(R path) if (isRandomAccessRange!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  ||
     isNarrowString!R)

auto extension(R)(R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  isSomeChar!(ElementType!R)  ||
     is(StringTypeOf!R))

Params: path = A path name. Returns: The extension part of a file name, including the dot.

auto stripExtension(R)(R path) if (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  && !isSomeString!R)

Remove extension from path.

fnauto stripExtension(C)(C[] path) if (isSomeChar!C)Ditto

private fnauto _stripExtension(R)(R path)

immutable(C1)[] setExtension(C1,  C2)(in  C1[]  path,  in  C2[]  ext) if (isSomeChar!C1 && !is(C1 ==  immutable)  &&  is(immutable  C1 ==  immutable  C2))

Sets or replaces an extension.

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

ditto

auto withExtension(R,  C)(R path,  C[]  ext) if (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  &&
    !isSomeString!R &&  isSomeChar!C)

Replace existing extension on filespec with new one.

fnauto withExtension(C1, C2)(C1[] path, C2[] ext) if (isSomeChar!C1 && isSomeChar!C2)Ditto

private fnauto _withExtension(R, C)(R path, C[] ext)

immutable(C1)[] defaultExtension(C1,  C2)(in  C1[]  path,  in  C2[]  ext) if (isSomeChar!C1 &&  is(immutable  C1 ==  immutable  C2))

Params: path = A path name. ext = The default extension to use.

auto withDefaultExtension(R,  C)(R path,  C[]  ext) if (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R &&  isSomeChar!(ElementType!R)  &&
    !isSomeString!R &&  isSomeChar!C)

Set the extension of `path` to `ext` if `path` doesn't have one.

fnauto withDefaultExtension(C1, C2)(C1[] path, C2[] ext) if (isSomeChar!C1 && isSomeChar!C2)Ditto

private fnauto _withDefaultExtension(R, C)(R path, C[] ext)

immutable(ElementEncodingType!(ElementType!Range))[] buildPath(Range)(scope  Range segments) if (isInputRange!Range && !isInfinite!Range &&  isSomeString!(ElementType!Range))

Combines one or more path segments.

fnimmutable(C)[] buildPath(C)(const(C)[][] paths...) if (isSomeChar!C) @safe pure nothrowditto

auto chainPath(R1,  R2,  Ranges...)(R1 r1,  R2 r2,  Ranges ranges) 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))))
    )

Concatenate path segments together to form one path.

auto chainPath(Ranges...)(auto  ref  Ranges ranges) if (Ranges.length >=  2 &&
     std.meta.anySatisfy!(isConvertibleToString,  Ranges))

fnimmutable(C)[] buildNormalizedPath(C)(const(C[])[] paths...) if (isSomeChar!C) @safe pure nothrowPerforms the same task as buildPath, while at the same time resolving current/parent directory symbols (`"."` and `".."`) and removing superfluous directory separators. It will return "." if the pa...

auto asNormalizedPath(R)(return  scope  R path) if (isSomeChar!(ElementEncodingType!R)  &&
    (isRandomAccessRange!R &&  hasSlicing!R &&  hasLength!R ||  isNarrowString!R)  &&
    !isConvertibleToString!R)

Normalize a path by resolving current/parent directory symbols (`"."` and `".."`) and removing superfluous directory separators. It will return "." if the path leads to the starting directory. On W...

fnauto asNormalizedPath(R)(return scope auto ref R path) if (isConvertibleToString!R)

auto pathSplitter(R)(R path) if ((isRandomAccessRange!R &&  hasSlicing!R ||
     isNarrowString!R)  &&
    !isConvertibleToString!R)

Slice up a path into its elements.

fnauto pathSplitter(R)(auto ref R path) if (isConvertibleToString!R)

bool isRooted(R)(R path) if (isRandomAccessRange!R &&  isSomeChar!(ElementType!R)  ||
     is(StringTypeOf!R))

Determines whether a path starts at a root directory.

fnstring absolutePath(return scope const string path, lazy string base = getcwd()) @safe pureTransforms `path` into an absolute path.

auto asAbsolutePath(R)(R path) if ((isRandomAccessRange!R &&  isSomeChar!(ElementType!R)  ||
     isNarrowString!R)  &&
    !isConvertibleToString!R)

Transforms `path` into an absolute path.

fnauto asAbsolutePath(R)(auto ref R path) if (isConvertibleToString!R)

fnstring relativePath(CaseSensitive cs = CaseSensitive.osDefault)(string path, lazy string base = getcwd())Translates `path` into a relative path.

auto asRelativePath(CaseSensitive cs =  CaseSensitive.osDefault,  R1,  R2)(R1 path,  R2 base) if ((isNarrowString!R1 ||
    (isRandomAccessRange!R1 &&  hasSlicing!R1 &&  isSomeChar!(ElementType!R1))  &&
    !isConvertibleToString!R1)  &&
    (isNarrowString!R2 ||
    (isRandomAccessRange!R2 &&  hasSlicing!R2 &&  isSomeChar!(ElementType!R2))  &&
    !isConvertibleToString!R2))

Transforms `path` into a path relative to `base`.

auto asRelativePath(CaseSensitive cs =  CaseSensitive.osDefault,  R1,  R2)(auto  ref  R1 path,  auto  ref  R2 base) if (isConvertibleToString!R1 ||  isConvertibleToString!R2)

fnint filenameCharCmp(CaseSensitive cs = CaseSensitive.osDefault)(dchar a, dchar b) @safe pure nothrowCompares filename characters.

int filenameCmp(CaseSensitive cs =  CaseSensitive.osDefault,  Range1,  Range2)(Range1 filename1,  Range2 filename2) if (isSomeFiniteCharInputRange!Range1 && !isConvertibleToString!Range1 &&
     isSomeFiniteCharInputRange!Range2 && !isConvertibleToString!Range2)

Compares file names and returns

int filenameCmp(CaseSensitive cs =  CaseSensitive.osDefault,  Range1,  Range2)(auto  ref  Range1 filename1,  auto  ref  Range2 filename2) if (isConvertibleToString!Range1 ||  isConvertibleToString!Range2)

bool globMatch(CaseSensitive cs =  CaseSensitive.osDefault,  C,  Range)(Range path,  const(C)[]  pattern) if (isForwardRange!Range && !isInfinite!Range &&
     isSomeChar!(ElementEncodingType!Range)  && !isConvertibleToString!Range &&
     isSomeChar!C &&  is(immutable  C ==  immutable  ElementEncodingType!Range))

@safe pure nothrowMatches a pattern against a path.

bool globMatch(CaseSensitive cs =  CaseSensitive.osDefault,  C,  Range)(auto  ref  Range path,  const(C)[]  pattern) if (isConvertibleToString!Range)

@safe pure nothrow

bool isValidFilename(Range)(Range filename) if ((isRandomAccessRange!Range &&  hasLength!Range &&  hasSlicing!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range)

Checks that the given file or directory name is valid.

fnbool isValidFilename(Range)(auto ref Range filename) if (isConvertibleToString!Range)

bool isValidPath(Range)(Range path) if ((isRandomAccessRange!Range &&  hasLength!Range &&  hasSlicing!Range &&  isSomeChar!(ElementEncodingType!Range)  ||
     isNarrowString!Range)  &&
    !isConvertibleToString!Range)

Checks whether `path` is a valid path.

fnbool isValidPath(Range)(auto ref Range path) if (isConvertibleToString!Range)

fnstring expandTilde(return scope const string inputPath) @safe nothrowPerforms tilde expansion in paths on POSIX systems. On Windows, this function does nothing.

Templates 1

tmplBaseOf(R)