License:
BSD style: see license.txt

Version:
Oct 2004: Initial version

Version:
Nov 2006: Australian version

Version:
Feb 2007: Mutating version

Version:
Mar 2007: Folded FileProxy in

Version:
Nov 2007: VFS dictates '/' always be used

Version:
Feb 2008: Split file-system calls into a struct

author:
Kris

FilePath combined a means of efficiently editing and extracting path components and of accessing the underlying file system.

Use module Path.d instead when you need only pedestrian access to the file-system, and are not manipulating the path components. Use FilePath for other scenarios, since it will often be notably more efficient

$(DDOC_MODULE_MEMBERS
  • class FilePath : tango.io.FilePath.PathView;
    • $(DDOC_DECL_DD Models a file path. These are expected to be used as the constructor argument to various file classes. The intention is that they easily convert to other representations such as absolute, canonical, or Url.

    File paths containing non-ansi characters should be UTF-8 encoded. Supporting Unicode in this manner was deemed to be more suitable than providing a wchar version of FilePath , and is both consistent & compatible with the approach taken with the Uri class.

    FilePath is designed to be transformed, thus each mutating method modifies the internal content. There is a read-only base-class called PathView, which can be used to provide a view into the content as desired.

    Note that patterns of adjacent '.' separators are treated specially in that they will be assigned to the name instead of the suffix. In addition, a '.' at the start of a name signifies it does not belong to the suffix i.e. ".file" is a name rather than a suffix.

    Note also that normalization of path-separators occurs by default. This means that the use of '\' characters will be converted into '/' instead while parsing. To mutate the path into an O/S native version, use the native() method. To obtain a copy instead, use the path.dup.native sequence

  • alias Filter ;
    • Filter used for screening paths via toList()

  • static FilePath opCall (char[] filepath = null);
    • Call-site shortcut to create a FilePath instance. This enables the same syntax as struct usage, so may expose a migration path

  • this(char[] filepath = null);
    • Create a FilePath from a copy of the provided string.

    FilePath assumes both path & name are present, and therefore may split what is otherwise a logically valid path. That is, the 'name' of a file is typically the path segment following a rightmost path-separator. The intent is to treat files and directories in the same manner; as a name with an optional ancestral structure. It is possible to bias the interpretation by adding a trailing path-separator to the argument. Doing so will result in an empty name attribute.

    With regard to the filepath copy, we found the common case to be an explicit .dup, whereas aliasing appeared to be rare by comparison. We also noted a large proportion interacting with C-oriented OS calls, implying the postfix of a null terminator. Thus, FilePath combines both as a single operation.



  • final char[] toString ();
    • Return the complete text of this filepath

  • final FilePath dup ();
    • Duplicate this path

  • final char[] cString ();
    • Return the complete text of this filepath as a null terminated string for use with a C api. Use toString instead for any D api.

    Note that the nul is always embedded within the string maintained by FilePath, so there's no heap overhead when making a C call



  • final char[] root ();
    • Return the root of this path. Roots are constructs such as "c:"

  • final char[] folder ();
    • Return the file path. Paths may start and end with a "/". The root path is "/" and an unspecified path is returned as an empty string. Directory paths may be split such that the directory name is placed into the 'name' member; directory paths are treated no differently than file paths

  • final char[] parent ();
    • Returns a path representing the parent of this one. This will typically return the current path component, though with a special case where the name component is empty. In such cases, the path is scanned for a prior segment: 
    
normal:
    
/x/y/z => /x/y


    
special:
    
/x/y/  => /x

                    Note that this returns a path suitable for splitting into
                path and name components (there's no trailing separator).

                See pop() also, which is generally more useful when working
                with FilePath instances

        

    


    


    



  • final char[] 
name
();

    • 


    Return the 
name
 of this file, or directory.


    


    



  • final char[] 
ext
();

    • 


    Ext is the tail of the filename, rightward of the rightmost
                '.' separator e.g. path "foo.bar" has 
ext
 "bar". Note that
                patterns of adjacent separators are treated specially; for
                example, ".." will wind up with no 
ext
 at all


    


    



  • final char[] 
suffix
();

    • 


    Suffix is like ext, but includes the separator e.g. path
                "foo.bar" has 
suffix
 ".bar"


    


    



  • final char[] 
path
();

    • 


    return the root + folder combination


    


    



  • final char[] 
file
();

    • 


    return the name + suffix combination


    


    



  • final int 
opEquals
(Object o);

    • 


    Returns true if all fields are equal.


    


    



  • final int 
opEquals
(char[] s);

    • 


    Does this FilePath equate to the given text?


    


    



  • final bool 
isAbsolute
();

    • 


    Returns true if this FilePath is *not* relative to the
                current working directory


    


    



  • final bool 
isEmpty
();

    • 


    Returns true if this FilePath is empty


    


    



  • final bool 
isChild
();

    • 


    Returns true if this FilePath has a parent. Note that a
                parent is defined by the presence of a path-separator in
                the path. This means 'foo' within "\foo" is considered a
                child of the root


    


    



  • final FilePath 
replace
(char from, char to);

    • 


    Replace all 'from' instances with 'to'


    


    



  • final FilePath 
standard
();

    • 


    Convert path separators to a 
standard
 format, using '/' as
                the path separator. This is compatible with URI and all of
                the contemporary O/S which Tango supports. Known exceptions
                include the Windows command-line processor, which considers
                '/' characters to be switches instead. Use the native()
                method to support that.


    
Note:
    
mutates the current path.


    

        


    


    



  • final FilePath 
native
();

    • 


    Convert to 
native
 O/S path separators where that is required,
                such as when dealing with the Windows command-line.


    
Note:
    
mutates the current path. Use this pattern to obtain a
                copy instead: path.dup.
native



    

        


    


    



  • final FilePath 
cat
(char[][] others...);

    • 


    Concatenate text to this path; no separators are added.
                See join() also


    


    



  • final FilePath 
append
(char[] path);

    • 


    Append a folder to this path. A leading separator is added
                as required


    


    



  • final FilePath 
prepend
(char[] path);

    • 


    Prepend a folder to this path. A trailing separator is added
                if needed


    


    



  • FilePath 
set
(FilePath path);

    • 


    Reset the content of this path to that of another and
                reparse


    


    



  • final FilePath 
set
(char[] path);

    • 


    Reset the content of this path, and reparse.


    


    



  • final FilePath 
isFolder
(bool folder);

    • 


    Sidestep the normal lookup for paths that are known to
                be folders. Where folder is true, file-system lookups
                will be skipped.


    


    



  • final FilePath 
root
(char[] other);

    • 


    Replace the 
root
 portion of this path


    


    



  • final FilePath 
folder
(char[] other);

    • 


    Replace the 
folder
 portion of this path. The 
folder
 will be
                padded with a path-separator as required


    


    



  • final FilePath 
name
(char[] other);

    • 


    Replace the 
name
 portion of this path


    


    



  • final FilePath 
suffix
(char[] other);

    • 


    Replace the 
suffix
 portion of this path. The 
suffix
 will be
                prefixed with a file-separator as required


    


    



  • final FilePath 
path
(char[] other);

    • 


    Replace the root and folder portions of this 
path
 and
                reparse. The replacement will be padded with a 
path

                separator as required


    


    



  • final FilePath 
file
(char[] other);

    • 


    Replace the 
file
 and suffix portions of this path and
                reparse. The replacement will be prefixed with a suffix
                separator as required


    


    



  • final FilePath 
pop
();

    • 


    Pop to the parent of the current filepath (in situ - mutates
                this FilePath)


    


    



  • static char[] 
join
(char[][] paths...);

    • 


    Join a set of path specs together. A path separator is
                potentially inserted between each of the segments.


    


    



  • static char[] 
stripped
(char[] path, char c = '/');

    • 


    Return an adjusted path such that non-empty instances do not
                have a trailing separator


    


    



  • static char[] 
padded
(char[] path, char c = '/');

    • 


    Return an adjusted path such that non-empty instances always
                have a trailing separator


    


    



  • static char[] 
prefixed
(char[] s, char c = '/');

    • 


    Return an adjusted path such that non-empty instances always
                have a 
prefixed
 separator


    


    



  • final FilePath 
create
();

    • 


    file-system methods 


    
Create an entire path consisting of this folder along with
                all parent folders. The path must not contain '.' or '..'
                segments. Related methods include PathUtil.normalize() and
                FileSystem.toAbsolute()


    

                Note that each segment is created as a folder, including the
                trailing segment.



    
Returns:
    
a chaining reference (this)



    
Throws:
    
IOException upon systen errors



    
Throws:
    
IllegalArgumentException if a segment exists but as
                a file instead of a folder


    

        


    


    



  • final FilePath[] 
toList
(bool delegate(FilePath, bool) filter = null);

    • 


    List the set of filenames within this folder, using
                the provided filter to control the list:

                    bool delegate (FilePath path, bool isFolder) Filter

    


    
Returning true from the filter includes the given path,
                whilst returning false excludes it. Parameter 'isFolder'
                indicates whether the path is a file or folder.


    

                Note that paths composed of '.' characters are ignored.


    

        


    


    



  • static FilePath 
from
(ref FileInfo info);

    • 


    Construct a FilePath 
from
 the given FileInfo


    


    



  • final bool 
exists
();

    • 


    Does this path currently exist?


    


    



  • final Time  
modified
();

    • 


    Returns the time of the last modification. Accurate
                to whatever the OS supports, and in a format dictated
                by the file-system. For example NTFS keeps UTC time,
                while FAT timestamps are based on the local time.


    


    



  • final Time  
accessed
();

    • 


    Returns the time of the last access. Accurate to
                whatever the OS supports, and in a format dictated
                by the file-system. For example NTFS keeps UTC time,
                while FAT timestamps are based on the local time.


    


    



  • final Time  
created
();

    • 


    Returns the time of file creation. Accurate to
                whatever the OS supports, and in a format dictated
                by the file-system. For example NTFS keeps UTC time,
                while FAT timestamps are based on the local time.


    


    



  • final FilePath 
rename
(FilePath dst);

    • 


    change the name or location of a file/directory, and
                adopt the provided Path


    


    



  • final FilePath 
copy
(char[] source);

    • 


    Transfer the content of another file to this one. Returns a
                reference to this class on success, or throws an IOException
                upon failure.


    


    



  • final ulong 
fileSize
();

    • 


    Return the file length (in bytes)


    


    



  • final bool 
isWritable
();

    • 


    Is this file writable?


    


    



  • final bool 
isFolder
();

    • 


    Is this file actually a folder/directory?


    


    



  • final Stamps  
timeStamps
();

    • 


    Return timestamp information


    
Timstamps are returns in a format dictated by the
                file-system. For example NTFS keeps UTC time,
                while FAT timestamps are based on the local time


    

        


    


    



  • final FilePath 
copy
(FilePath src);

    • 


    Transfer the content of another file to this one. Returns a
                reference to this class on success, or throws an IOException
                upon failure.


    


    



  • final FilePath 
remove
();

    • 


    Remove the file/directory from the file-system


    


    



  • final FilePath 
rename
(char[] dst);

    • 


    change the name or location of a file/directory, and
               adopt the provided Path


    


    



  • final FilePath 
createFile
();

    • 


    Create a new file


    


    



  • final FilePath 
createFolder
();

    • 


    Create a new directory


    


    



  • final int 
opApply
(int delegate(ref FileInfo ) dg);

    • 


    List the set of filenames within this folder.


    
Each path and filename is passed to the provided
                delegate, along with the path prefix and whether
                the entry is a folder or not.


    

                Returns the number of files scanned.


    

        


    


    





  • interface 
PathView
;

    • 




    



    


  • abstract char[] 
toString
();

    • 


    Return the complete text of this filepath


    


    



  • abstract char[] 
cString
();

    • 


    Return the complete text of this filepath


    


    



  • abstract char[] 
root
();

    • 


    Return the 
root
 of this path. Roots are constructs such as
                "c:"


    


    



  • abstract char[] 
folder
();

    • 


    Return the file path. Paths may start and end with a "/".
                The root path is "/" and an unspecified path is returned as
                an empty string. Directory paths may be split such that the
                directory name is placed into the 'name' member; directory
                paths are treated no differently than file paths


    


    



  • abstract char[] 
name
();

    • 


    Return the 
name
 of this file, or directory, excluding a
                suffix.


    


    



  • abstract char[] 
ext
();

    • 


    Ext is the tail of the filename, rightward of the rightmost
                '.' separator e.g. path "foo.bar" has 
ext
 "bar". Note that
                patterns of adjacent separators are treated specially; for
                example, ".." will wind up with no 
ext
 at all


    


    



  • abstract char[] 
suffix
();

    • 


    Suffix is like ext, but includes the separator e.g. path
                "foo.bar" has 
suffix
 ".bar"


    


    



  • abstract char[] 
path
();

    • 


    return the root + folder combination


    


    



  • abstract char[] 
file
();

    • 


    return the name + suffix combination


    


    



  • abstract bool 
isAbsolute
();

    • 


    Returns true if this FilePath is *not* relative to the
                current working directory.


    


    



  • abstract bool 
isEmpty
();

    • 


    Returns true if this FilePath is empty


    


    



  • abstract bool 
isChild
();

    • 


    Returns true if this FilePath has a parent


    


    



  • abstract bool 
exists
();

    • 


    Does this path currently exist?


    


    



  • abstract Time  
modified
();

    • 


    Returns the time of the last modification. Accurate
                to whatever the OS supports


    


    



  • abstract Time  
accessed
();

    • 


    Returns the time of the last access. Accurate to
                whatever the OS supports


    


    



  • abstract Time  
created
();

    • 


    Returns the time of file creation. Accurate to
                whatever the OS supports


    


    



  • abstract ulong 
fileSize
();

    • 


    Return the file length (in bytes)


    


    



  • abstract bool 
isWritable
();

    • 


    Is this file writable?


    


    



  • abstract bool 
isFolder
();

    • 


    Is this file actually a folder/directory?


    


    



  • abstract Stamps  
timeStamps
();

    • 


    Return timestamp information


    


    

    


    

    


    
                
    
                        Copyright (c) 2004 Kris Bell. All rights reserved

 :: page rendered by CandyDoc