# dmd.root.filename

Encapsulate path and file names.

#### Authors

Walter Bright, http://www.digitalmars.com

#### License

Boost License 1.0

Source: root/filename.d

Documentation: https://dlang.org/phobos/dmd_root_filename.html

Coverage: https://codecov.io/gh/dlang/dmd/src/master/src/dmd/root/filename.d

- `FileName`

  #### Declaration

  `struct `FileName`;`

  Encapsulate path and file names.

  - `this`

    #### Declaration

    `pure nothrow this(const(char)[] `str`);`

  - `equals`

    #### Declaration

    `static pure nothrow @nogc bool `equals`(const(char)* `name1`, const(char)* `name2`);
    static pure nothrow @nogc bool `equals`(const(char)[] `name1`, const(char)[] `name2`);`

    Compare two name according to the platform's rules (case sensitive or not)

  - `absolute`

    #### Declaration

    `static pure nothrow @nogc bool `absolute`(const(char)* `name`);
    static pure nothrow @nogc bool `absolute`(const(char)[] `name`);`

    Determine if path is `absolute`.

    #### Parameters

    `const(char)* `name`` | path

    #### Return Value

    `true` if `absolute` path `name`.

  - `toAbsolute`

    #### Declaration

    `static nothrow const(char)* `toAbsolute`(const(char)* `name`, const(char)* `base` = null);`

    Return the given `name` as an absolute path

    #### Parameters

    `const(char)* `name`` | path
    `const(char)* `base`` | the absolute `base` to prefix `name` with if it is relative

    #### Return Value

    `name` as an absolute path relative to `base`

  - `ext`

    #### Declaration

    `static pure nothrow @nogc const(char)* `ext`(const(char)* `str`);
    static pure nothrow @nogc @safe const(char)[] `ext`(const(char)[] `str`);`

    Determine file name extension as slice of input.

    #### Parameters

    `const(char)* `str`` | file name

    #### Return Value

    filename extension (read-only). Points past '.' of extension. If there isn't one, return `null`.

  - `removeExt`

    #### Declaration

    `static nothrow const(char)* `removeExt`(const(char)* `str`);
    static nothrow const(char)[] `removeExt`(const(char)[] `str`);`

    Return file name without extension.

    TODO: Once slice are used everywhere and `\0` is not assumed, this can be turned into a simple slicing.

    #### Parameters

    `const(char)* `str`` | file name

    #### Return Value

    mem.xmalloc'd filename with extension removed.

  - `name`

    #### Declaration

    `static pure nothrow @nogc const(char)* `name`(const(char)* `str`);
    static pure nothrow @nogc const(char)[] `name`(const(char)[] `str`);`

    Return filename `name` excluding path (read-only).

  - `path`

    #### Declaration

    `static nothrow const(char)* `path`(const(char)* `str`);
    static nothrow const(char)[] `path`(const(char)[] `str`);`

    Return `path` portion of `str`. returned string is newly allocated Path does not include trailing `path` separator.

  - `replaceName`

    #### Declaration

    `static nothrow const(char)[] `replaceName`(const(char)[] `path`, const(char)[] `name`);`

    Replace filename portion of `path`.

  - `combine`

    #### Declaration

    `static nothrow const(char)* `combine`(const(char)* `path`, const(char)* `name`);
    static nothrow const(char)[] `combine`(const(char)[] `path`, const(char)[] `name`);`

    Combine a ``path`` and a file ``name``

    #### Parameters

    `const(char)* `path`` | Path to append to
    `const(char)* `name`` | Name to append to `path`

    #### Return Value

    The `\0` terminated string which is the combination of ``path`` and ``name`` and a valid `path`.

  - `splitPath`

    #### Declaration

    `static nothrow void `splitPath`(int delegate(const(char)*) nothrow `sink`, const(char)* `path`);`

    Split `path` (such as that returned by `getenv("PATH")`) into pieces, each piece is mem.xmalloc'd Handle double quotes and ~. Pass the pieces to `sink`()

    #### Parameters

    `int delegate(const(char)*) nothrow `sink`` | send the `path` pieces here, end when `sink`() returns !=0
    `const(char)* `path`` | the `path` to split up.

  - `addExt`

    #### Declaration

    `static pure nothrow char[] `addExt`(const(char)[] `name`, const(char)[] `ext`);`

    Add the extension ``ext`` to ``name``, regardless of the content of ``name``

    #### Parameters

    `const(char)[] `name`` | Path to append the extension to
    `const(char)[] `ext`` | Extension to add (should not include '.')

    #### Return Value

    A newly allocated string (free with `FileName.free`)

  - `defaultExt`

    #### Declaration

    `static nothrow const(char)* `defaultExt`(const(char)* `name`, const(char)* `ext`);
    static nothrow const(char)[] `defaultExt`(const(char)[] `name`, const(char)[] `ext`);`

    Free returned value with FileName::free()

  - `forceExt`

    #### Declaration

    `static nothrow const(char)* `forceExt`(const(char)* `name`, const(char)* `ext`);
    static nothrow const(char)[] `forceExt`(const(char)[] `name`, const(char)[] `ext`);`

    Free returned value with FileName::free()

  - `equalsExt`

    #### Declaration

    `static pure nothrow @nogc bool `equalsExt`(const(char)* `name`, const(char)* `ext`);
    static pure nothrow @nogc bool `equalsExt`(const(char)[] `name`, const(char)[] `ext`);`

    #### Return Value

    `true` if ``name``'s extension is ``ext``

  - `equalsExt`

    #### Declaration

    `const pure nothrow @nogc bool `equalsExt`(const(char)* `ext`);`

    Return !=0 if extensions match.

  - `searchPath`

    #### Declaration

    `static nothrow const(char)* `searchPath`(Strings* `path`, const(char)* `name`, bool `cwd`);`

    Search paths for file.

    #### Parameters

    `Strings* `path`` | array of `path` strings
    `const(char)* `name`` | file to look for
    `bool `cwd`` | `true` means search current directory before searching `path`

    #### Return Value

    if found, filename combined with `path`, otherwise `null`

  - `safeSearchPath`

    #### Declaration

    `static nothrow const(char)* `safeSearchPath`(Strings* `path`, const(char)* `name`);`

    Search Path for file in a safe manner.

    #### Discussion

    Be wary of CWE-22: Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal') attacks. http://cwe.mitre.org/data/definitions/22.html More info: https://www.securecoding.cert.org/confluence/display/c/FIO02-C.+Canonicalize+path+names+originating+from+tainted+sources

    #### Return Value

    NULL file not found !=NULL mem.xmalloc'd file `name`

  - `exists`

    #### Declaration

    `static nothrow int `exists`(const(char)* `name`);
    static nothrow int `exists`(const(char)[] `name`);`

    Check if the file the `path` points to `exists`

    #### Return Value

    0 if it does not `exists` 1 if it `exists` and is not a directory 2 if it `exists` and is a directory

  - `ensurePathExists`

    #### Declaration

    `static nothrow bool `ensurePathExists`(const(char)[] `path`);
    static nothrow bool `ensurePathExists`(const(char)* `path`);`

    Ensure that the provided `path` exists

    #### Discussion

    Accepts a `path` to either a file or a directory. In the former case, the basepath (`path` to the containing directory) will be checked for existence, and created if it does not exists. In the later case, the directory pointed to will be checked for existence and created if needed.

    #### Parameters

    `const(char)[] `path`` | a `path` to a file or a directory

    #### Return Value

    `true` if the directory exists or was successfully created

  - `canonicalName`

    #### Declaration

    `static nothrow const(char)* `canonicalName`(const(char)* `name`);
    static nothrow const(char)[] `canonicalName`(const(char)[] `name`);`

    Return canonical version of `name`. This code is high risk.

  - `free`

    #### Declaration

    `static pure nothrow void `free`(const(char)* `str`);`

    Free memory allocated by FileName routines