next_inactive up previous


DirectoryContainer: Руководство Программиста
DocumentId:GradSoft-PR-r-09.01.2001-v1.0.0


Contents

Bведение

DirectoryContainer - это кроcсплатформенная компонета на C++, предназначенная для навигации по списку имен файлов в директории. Используя DirectoryIterator, Вы получаете простое и, важно, одинаковое API для действий, связанных с просмотром директории (таких как поиск файлов), для UNIX и для Windows NT. Пакет DirectoryIterator разработан и поддерживается компанией GradSoft и поставляется в исходных кодах. Домашняя страница разработчика http://www.gradsoft.kiev.ua/

Этот документ является неформальным описанием пакета. Полная специфиткация находится в описании API (http://www.gradsoft.kiev.ua/common/ToolBox/DirectoryContainer/API/)

Общий порядок использования

Общие сведения

Реализованы два следующих подхода к порядку чтения директории:

  1. Объект DirectoryEntry позволяет работать с директорией традиционно как c потоком ввода;
  2. Объект DirectoryContainer позволяет работать с директорией как c STL-контейнером для элементов DirectoryEntry.

Объект DirectoryEntry

Общие сведения

Объект DirectoryEntry представляет собой позиционируемый объект для работы с директорией как c потоком ввода. Это значит что:

  1. Директория рассматриватся как последовательность элементов, доступ к которым возможен через единственнный доступный указатель на "текущий" элемент;

    DirectoryEntry рассматриватся как средство доступа к единственному (текущему) элементу последовательности, который, однако, можно сменить при помощи собственых средств DirectoryEntry.

  2. Для того, чтобы прочесть директорию, мы должны сначала ее "открыть", а потом (вообще говоря) "закрыть".
В нашем случае директория открывается в момент создания объекта DirectoryEntry, поэтому, для того, чтобы получить информацию о некотором элементе некоторой директории, мы должны:
  1. Создать объект DirectoryEntry для заданной директории и позиционировать его на заданном элементе;
  2. Вызвать метод, возвращающий информацию о текущем элементе последовательности.

Пример: 

try{

  DirectoryEntry smth(".");  // создать объект и позиционировать его 
                             // на первом элементе последовательности
  do {

   cout<<smth.name()<<endl;  // вывести имя текущего элемента

  } while(smth.next());      // позиционировать объект на следующем 
                             // элементе последовательности

} catch(DirectoryException& ex) {   // см.ниже

  cerr << ex.message << endl;
}
Данный код выводит имена файлов/поддиректорий, расположенных в текущей директории диска

API

Общие сведения:

Класс DirectoryEntry реализует модели Assignable и EqualityComparable, т.е. имеет:

  1. Конструктор копирования и оператор "=";
  2. Операторы "==" и "!=".
В то же время класс не является DеfaultConstructable, его стандартный конструктор объявлен приватным.

Описание методов:

  1. Стандартные средства:

  2. Средства управления потоком:

  3. Методы, возвращающие информацию о текущем элементе последовательности:

    Внимание: если достигнут конец списка, значения, возвращаемые этими методами, не определены.

Замечания:

Объект DirectoryContainer

Общие сведения

DirectoryContainer представляет собой класс, который позволяет работать с директорией как c STL-контейнером для элементов DirectoryEntry. Объект DirectoryEntry при этом рассматривается исключительно как средство доступа к одной-единственной записи директории, позиционирование объекта DirectoryEntry его собственными средствами запрещено. Сопряженный с контейнером итераторный тип реализован объектом DirectoryIterator 2.4 который представляет собой Forward Iterator для последоватеьности объектов DirectoryEntry

Пример: 

DirectoryContainer dir(".");

DirectoryContainer::iterator it; 

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

Этот код делает то же, что и предыдущий, с поправкой на то, что скобки try{ }catch здесь опущены.

API

Сопряженные типы:

Описание методов:

  1. Стандартные средства:

  2. Специальные средства:

Замечания:


Класс DirectoryIterator

DirectoryIterator представляет собой служебный класс, который является Forward-итератором для последовательности элементов DirectoryEntry. Как Forward Iterator, он имеет следующие методы:

а также стандартный конструктор DirectoryIterator(), который дает итератор, указывающий на виртуальный элемент "после последнего"

Исключение DirectoryException

DirectoryException представляет собой исключение, которое генерируется следующими методами класса DirectoryEntry:

при ошибках системы, а также конструктором DirectoryEntry(cont *char) в том случае, когда директория, имя которой передано в виде параметра, не существует. Т.к. DirectoryIterator и DirectoryContainer являются надстройками над DirectoryEntry, класс DirectoryException может быть послан следующими методами класса DirectoryIterator: а также следующими методами класса DirectoryContainer:

API: 

struct DirectoryException
{
  long errno; // номер ошибки ОС
  string message; // стандартное сообщение о системной ошибке
}

Простой пример

Данный пример демонстрирует порядок использования пакета DirectoryContainer: 

#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(const DirectoryException& ex) {
  
    cerr << ex.message << endl;
  }
  return 0;
}

Соглашения относительно программной среды

Если Вы работаете под управлением Windows NT, Вам необходимо:

  1. определить макрос WIN32 перед включением файла DirectoryContainer.h
  2. использовать "новые" библиотеки и, соответственно, заголовочные файлы iostream, fstream и т.п. вместо аналогичных iostream.h, fstream.h и т.п.

История документа

16-10-2002
исправлено несколько опечаток.
03-01-2002
обновлен в соответствии с новой версией пакета 1.4.0
03-07-2001
DirectoryIterator переименован в DirectoryContainer
16-05-2001
Текст приведен в соответствие с изменениями в коде
09-01-2001
Первая русская редакция.
15-01-2001
FileIterator переименован в DirectoryIterator

next_inactive up previous
GradSoft