next_inactive up previous

DirectoryContainer : Programmer Guide



This package DirectoryContainer is a cross-platform C++ component for reading file directory. Using DirectoryContainer, you receives a simple API for actions such as searching file, the same for UNIX and for Windows 32. The package is supplied as source code. The package is created and suppported by GradSopft company, the home page of GradSoft is

This document is non-formal description of package, full specification are in API reference. (

Principles of using

General information

Two next approach to the reading of the directory is realized:

  1. You can use a DirectoryEntry object for handling directory like an input stream;
  2. You can use a DirectoryContainer object for handling directory like a container for elements of type DirectoryEntry.

Class DirectoryEntry

General information

DirectoryEntry is a being-positioned object for handling the directory like an input stream. These words means following:

    1. directory is considered to be a sequence of some (specific) elemets, access to which is possible by unique pointer to the "current" element;

    2. DirectoryEntry is designed to be a mean of handling of a single (the current) element which is replaceable, however, by own methods of DirectoryEntry.

  1. In order to directory was readed, that must be opend before and closed afterwards.
Using DirectoryEntry, the directory claimed will be opend along with object creation, so that to obtain information about certain file you must fulfill the next actions:
  1. To create DirectoryEntry and to position it at the file of interest;
  2. To invoke methods which returns information about current element of sequence.



  DirectoryEntry smth(".");  // create object and position it
                             // at the first element of sequence
  do {

   cout<<<<endl;  // display the name of element

  } while(;      // position object at the following 
                             // element of sequence (or break the loop)

} catch(DirectoryException& ex) {   // see below

  cerr << ex.message << endl;
This code display the list of files disposed in the current directory.


General information:

DirectoryEntry complies with models Assignable and EqualityComparable, i.e. it has:

  1. Copy constructor and operator= ;
  2. operator== and operator!=.
Nevertheless, it is'nt D┼faultConstructable, default constructor of it is private.

Description of methods:

  1. Means for complying with Assignable and EqualityComparable

  2. Means for creation and closing of stream:

  3. Means for positioning:

  4. Methods returning information about current element of sequence:

    Attention: if the object arrives at the end of file, then values returned by these methods are undefined.


Class DirectoryContainer

General information

DirectoryContainer constitutes a class which provide facilities to work with file directory like STL-container. The value type of DirectoryContainer is class DirectoryEntry, the iterator type is class DirectoryIterator (see below 2.4) being Forward Iterator for sequence of DirectoryEntry. In that context DirectoryEntry is considered to be a mean attendant upon fixed record of directory, positioning of this object by own means must not be fulfill.



  DirectoryContainer dir(".");

  DirectoryContainer::iterator it;

  for( it=dir.begin(); it!=dir.end(); ++it ) cout<< it->name() <<endl;

} catch(DirectoryException& ex) {

  cerr << ex.message << endl;
This code area has same functionality as that is typed above


Associated types:

Description of methods:

  1. Container's means:

  2. Specific means:


Class DirectoryIterator

DirectoryIterator is especial class being a Forward Iterator for sequence of DirectoryEntry. Thus, it has next methods:

and, then, a defaut constructor DirectoryIterator() which makes iterator for past-the-end element.

Class DirectoryException

DirectoryException is a class which may be thrown by DirectoryEntry methods

in the case of system error occur, and additionally by DirectoryEntry(cont *char) constructor in the case of directory with name being taken is not exist. As DirectoryIterator and DirectoryContainer are superstructures under DirectoryEntry, this class DirectoryException may be thrown by next DirectoryIterator's methods: and next DirectoryContainer's methods:


struct DirectoryException
  long errno; // system error number
  string message; // system error message

Full-fledged example

This code is full-fledged example of using of the package:

#include <GradSoft/DirectoryContainer.h>

#include <iostream>
using namespace std;
using namespace GradSoft;
#include <iostream.h>

#include <stdio.h>

int main(int argc, char** argv)

  if (argc!=2) {
    cerr << "Usage: " << argv[0] << " path" << endl;
    return 1;

  cout<<endl<<">>>> 1 >>>>"<<endl;
  // Usinig DirectoryEntry:
    DirectoryEntry smth(argv[1]);  
    do {
    } while(;  
  } catch(DirectoryContainer& ex) {
    cerr << ex.message << endl;
  cout<<endl<<">>>> 2 >>>>"<<endl;
  // Using DirectoryContainer:
    DirectoryContainer dir(argv[1]);
    Directory::iterator it;
    for( it=dir.begin(); it!=dir.end(); ++it)
      cout << it->name() ;
      if ( it->is_directory() ) cout << " ( DIR ) ";
      else cout << " ( " << it->fsize() << " ) ";
      cout << endl;
  } catch(DirectoryException& ex) {
    cerr << ex.message << endl;
  return 0;

Programming environment conventions

Using DirectoryContainer on Windows NT, you must:

  1. to define WIN32 macro before inclusion of DirectoryContainer.h header file;
  2. to use iostream, fstream, etc. standard headers instead iostream.h, fstream.h, etc. ones.


fixed incorrect URL for API reference.
updated in accordance with 1.4.0 public release.
last touch before 1.3.0 public release.
name changed to DirectoryContainer
bringing into accordance with changes in code.
initial revision of english text.
name changed to DirectoryIterator.

next_inactive up previous