Looking Up Entities with the IDirectory::lookUp Function

IDirectory provides the lookup function lookUp. This function will search in the directory for an entity with a specified name. If you pass a simple file name to lookUp, it will look for an entity with that name in the physical directory represented by the IDirectory object:

IFile myFile = aDirectory.lookUp("filename");

If you know the name of an entity and the directory in which it is located, use the method IDirectory::lookUp to find it. For example, to find a directory named abc inside a directory that is specified by the variable aDirectory, use this code:

IDirectory myDirectory = aDirectory.lookUp("abc");

If you pass in a partial path, lookUp will look for an entity in the specified subdirectory of the IDirectory. The following code will look for a subdirectory named direct and then for a file inside it named filename.

IFile aFile = dir.lookUp("direct/filename",
    IUnixPathNameParser());

Looking Up Entities with a Directory Iterator

Another way to find an entity is to search through an entire directory hierarchy or through all of the entities in a particular directory. This type of search is performed with iterators.

The following example searches through the directory tree under aDirectory for a file named "filename". Passing true in the second argument to the IDirectoryIterator makes the iteration recursive.

IDirectory aDirectory(...);
...
IFile myFile;
for (IDirectoryIterator anEntity(aDirectory, true);
    anEntity;
    anEntity++)
{
    if (anEntity->isA(IFile::kKind) &&
        anEntity->name() == "filename")
    {
        myFile = *anEntity;
        break;
    }
}

Iterating over the Contents of a Directory

IDirectoryIterator iterates over the contents of a single directory or an entire directory tree. The bool recursive argument to the constructor determines whether or not the iteration is recursive. Because directories can contain other directories as well as files, the results of iteration are often heterogeneous. The following simple example will print the names of all files in the current directory:

for (IDirectoryIterator anEntity(IDirectory::current());
    anEntity;
    anEntity++)
{
    if (anEntity->isA(IFile::kKind)) {
        cout << anEntity->name() << endl;
    }
}

Iterating over the Contents of a Volume

IVolume derives from IDirectory, so you can iterate over all the directories on a particular volume by creating an IDirectoryIterator object to which you pass an IVolume object during construction. Passing true in the second argument to the IDirectoryIterator constructor makes the iteration recursive.

IVolume theVolume(IHostPathName("/"),
    IUnixPathNameParser());

for (IDirectoryIterator anEntity(theVolume, true);
    anEntity;
    anEntity++)
{
    processEntity(*anEntity);
}

Iterating over all Mounted Volumes

You can iterate over all of the volumes mounted on a system. Instantiate and use an IVolumeIterator:

for (IVolumeIterator aVolume; aVolume; aVolume++) {
    processEntity(*aVolume);
}

Iterating over all Root Directories

You can also search through all of the topmost, or "parentless" directories, on the system. These directories are called root directories. IRootDirectoryIterator iterates over all root directories on all mounted volumes and returns an IDirectory for the top of each separate directory hierarchy on the system. For example, on a UNIX host there is only one root directory (named "/") for the entire system.

On a Windows or an OS/2 system, there is a one-to-one correspondence between root directories and volumes, so volume iterators and root-directory iterators return the same entities.

The following code will call the external function processEntity for every root directory on the system.

for (IRootDirectoryIterator aRoot; aRoot; aRoot++) {
    processEntity(*aRoot);
}

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

Instantiating a File System Entity from a Host-Specific Pathname
Instantiating a File System Entity from a Portable Pathname
Using an Instance of IFileSystemEntity to Represent a File, Directory or Volume
Instantiating Host-Specific Pathnames and Pathname Parsers
Instantiating a Portable Pathname from a Host-Specific Pathname
Testing the Identity of a File System Entity