Instantiating a File System Entity from a Host-Specific Pathname

If you know the host system's pathname for the object, you can use an entity constructor that takes the pathname as an argument. For example, the following code constructs an IFile for the file for which the host-specific pathname is specified by argv[1]:

IFile myFile(IHostPathName(argv[1]));

If your pathname is in the format for a different operating system, you can specify an object to use to parse the path:

IFile myFile(argv[1], IFile::kMustExist,
    IUnixPathNameParser());

The code in the above example will fail if there is no file at the location specified by argv[1].

The following code will create a directory named xyz in the subdirectory named sub.

IDirectory newDir = dir.createDirectory("sub/xyz",
    IUnixPathNameParser());

If sub does not exist, createDirectory will automatically create it too.

Note: If you do not specify a parser to use for a host-specific path that is not in the current host's format, one of the following will occur when the path is used:

• If the path is illegal for the current host's format, you will get an IInvalidName exception.
• If the path happens to be legal in the host's format, it might be interpreted differently than you expect. For example, if you create a file using the path "foo\bar" on a UNIX system, the file might create a file called "foo\bar" in the current directory.

Instantiating a File System Entity from a Portable Pathname

If you already have an IPathName object, you can use it to construct an entity instance that represents the physical object at the location specified by the path. You simply use IPathName in the entity instance's constructor:

IPathName aFullPath = ....;
IFile myFile(aFullPath);

If you have an IDirectory instance for the directory in which you wish to create an entity, you can also use the IDirectory methods createFile and createDirectory.

To create a file named "abc", you do this:

IDirectory aDirectory = ....;
IFile newFile = aDirectory.createFile("abc");

The following code shows how to specify a subdirectory relative to the current directory. In this case the subdirectory is named "subdirectory":

// use pathname relative to current directory
IFile myFile(IPathName("subdirectory"));

If you have a partial pathname relative to a known directory, you can use IDirectory::lookUp:

IPathName aPartialPath = ....;
IFile myFile = aDirectory.lookUp(aPartialPath);

Instantiating a File System Entity from Another Instance of the Same Entity Class

You can make a copy of a file system entity by using the entity class' copy constructor. In each of the following examples, both originalEntity and duplicateEntity will point to the same physical object on disk:

IFile originalEntity(pathName);
IFile duplicateEntity(originalEntity);

IDirectory originalEntity(pathName);
IDirectory duplicateEntity(originalEntity);

IVolume originalEntity(hostPathName);
IVolume duplicateEntity(originalEntity);

IFileSystemEntity originalEntity(pathName);
IFileSystemEntity duplicateEntity(originalEntity);

Using an Instance of IFileSystemEntity to Represent a File, Directory or Volume

Instantiate and use subclasses of IFileSystemEntity, such as IFile, when you need to manipulate a specific type of file system object. If you only need to represent file system entities generically and the functions provided by IFileSystemEntity are sufficient, you can use an instance of IFileSystemEntity to represent a file, directory or volume:

IFileSystemEntity fileEntity(filePathName);
IFileSystemEntity directoryEntity(dirPathName);
IFileSystemEntity volumeEntity(volHostPathName);

If you try to manipulate an IFileSystemEntity instance in a way that is inconsistent with the type of physical object which the entity represents, you will get an exception. For example:

IFileSystemEntity myEntity = IFile(filename);
...
IDirectory myDirectory = myEntity; // WRONG: myEntity
                                   // is not a directory!
                                   // An exception of type 
                                   // IEntityTypeMismatch is thrown.

Introduction to the File System
Overview of File System Entities
Overview of Pathnames and Pathname Parsers
File System Exceptions

Instantiating Host-Specific Pathnames and Pathname Parsers
Instantiating a Portable Pathname from a Host-Specific Pathname
Creating and Replacing Files and Directories
Creating a File or Directory and Intermediate Subdirectories