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

Contents

• Introduction
• Principles of using
  • General information
  • Class DirectoryEntry
  • Class DirectoryContainer
  • Class DirectoryIterator
  • Class DirectoryException
• Full-fledged example
• Programming environment conventions
• Changes

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. 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.

2. 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
   • DirectoryEntry(const DirectoryEntry& );
   • DirectoryEntry& operator=(const DirectoryEntry& );
   • bool operator==(const DirectoryEntry& ) const;
   • bool operator!=(const DirectoryEntry& ) const;

2. Means for creation and closing of stream:
   • DirectoryEntry(const char*) - open directory and position object at the first element

     Parameter: name of directory

   • close() - close directory
   • ~DirectoryEntry() - invoke close()

3. Means for positioning:
   • bool next() - position object at the next element of sequence

     Return value:

     -

     true, if positioning succeeds;

     -

     false, if object arrives at the end of file

   • bool find(const *char) - position object at the element with given name

     Parameter:

     the name of the file must be found

     Return value:

     -

     true, if positioning succeeds;

     -

     false, if object arrives at the end of file

4. Methods returning information about current element of sequence:
   • const char* name() - returns the name of current element (being file or subdirectory)
   • int fsize() - returns a size of file or 0 if current element is subdirectory
   • bool is_directory() - returns true, if current element is subdirectory and false otherwise
   • bool is_hidden() - returns true, if current element is hidden (this may be under Windows) and false otherwise
   Attention: if the object arrives at the end of file, then values returned by these methods are undefined.

Note:

• Two instances of DirectoryEntry is assigned be equil, if both are:
  1. not positioned (the end of files are achieved)
  2. positioned at the same element of the same directory supposing that the element is identified by name.

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:

• value_type - class DirectoryEntry
• iterator - class DirectoryIterator (2.4),
• const_iterator - the same as iterator
• reference - a reference to the DirectoryEntry
• const_reference - a constant reference to the DirectoryEntry
• pointer - a pointer to the DirectoryEntry
• distance_type - DirectoryIterator difference type (long)
• size_type - long

Description of methods:

1. Container's means:
   • DirectoryContainer(DirectoryContainer&);
   • DirectoryContainer& operator=(DirectoryContainer&);
   • DirectoryIterator begin();
   • static const DirectoryIterator& end();
   • size_type size();
   • size_type max_size();
   • bool empty();
   • void swap(DirectoryContainer&);

2. Specific means:
   • DirectoryContainer() - creates DirectoryContainer associated with current directory; Parameter: the name of directory;
   • DirectoryContainer(const char *path) - creates DirectoryContainer associated with given directory; Parameter: the name of directory;
   • setPath(const char *path) - associate DirectoryContainer with given directory; Parameter: the name of directory;
   • record_count() - returns a record count of the directory excepting pointer to the directory itself and pointer to the parent direectory; it is a size()-2 in most cases
   • bool no_records() - returns true, if the directory is not contain any records excepting pointer to the directory itself and pointer to the parent direectory, and false otherwize.

Note:

• Note a size() method returns the record count including special entry (which is a pointer to the directory itself and a pointer to the parent direectory), and, consequently, an empty() method returns false in most cases (excepting case of checking empty disk for Windows platform). Use no_files() method to check if the directory is empty in usual sense terms.

Class DirectoryIterator

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

• DirectoryIterator(const DirectoryIterator& );

• DirectoryIterator& operator=(const DirectoryIterator& );

• DirectoryIterator& operator++();

• DirectoryIterator operator++(int);

• DirectoryEntry& operator*();

• const DirectoryEntry& operator*() const;

• DirectoryEntry* operator->();

• const DirectoryEntry* operator->() const;

• bool operator==(const DirectoryIterator& );

• bool operator!=(const DirectoryIterator& );

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

• DirectoryEntry(const char* path);
• ~DirectoryEntry();
• DirectoryEntry(const DirectoryEntry& x);
• DirectoryEntry& operator=(const DirectoryEntry& x);
• bool next();
• bool find(const char* name);
• void close();

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:

• DirectoryIterator(const DirectoryIterator& );
• operator=(const DirectoryIterator& );
• operator++();
• operator++(int);

and next DirectoryContainer's methods:

• begin()
• record_count()
• no_files()
• size()
• empty()

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.