next_inactive up previous


DirectoryContainer : Programmer Guide
DocumentId:GradSoft-PR-e-11.12.2000-v1.0.0


Contents

Introduction

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 http://www.gradsoft.kiev.ua/.

This document is non-formal description of package, full specification are in API reference. (www.gradsoft.kiev.ua/common/ToolBox/DirectoryContainer/API/).

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.

Example:

try{

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

   cout<<smth.name()<<endl;  // display the name of element

  } while(smth.next());      // 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.

API

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.

Note:

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.

Example:

try{

  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

API

Associated types:

Description of methods:

  1. Container's means:

  2. Specific means:

Note:


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:

API:

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>

ifdef HAVE_NAMESPACES
#include <iostream>
using namespace std;
using namespace GradSoft;
#else
#include <iostream.h>
#endif

#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:
  
  try{
  
    DirectoryEntry smth(argv[1]);  
  
    do {
  
     cout<<smth.name()<<endl;  
  
    } while(smth.next());  
  
  } catch(DirectoryContainer& ex) {
  
    cerr << ex.message << endl;
  }
  
  cout<<endl<<">>>> 2 >>>>"<<endl;
  
  // Using DirectoryContainer:
  
  try{
  
    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.

Changes

16-10-2002
fixed incorrect URL for API reference.
03-01-2002
updated in accordance with 1.4.0 public release.
01-08-2001
last touch before 1.3.0 public release.
03-07-2001
name changed to DirectoryContainer
17-05-2001
bringing into accordance with changes in code.
11-12-2000
initial revision of english text.
15-01-2001
name changed to DirectoryIterator.


next_inactive up previous
GradSoft