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