QDirIterator から QDirListing への移植

Qt 6.8では、QDirIterator のより効率的な代替としてQDirListing が追加されました（ は現時点では引き続き利用可能です）。このページでは、QDirIterator をQDirListing へ移植する際に留意すべき点をいくつか紹介します。

QDirIterator では、QDirIterator::IteratorFlags とQDir::Filters という 2 つの別々の列挙型変数からフラグを使用して、どのエントリを一覧表示するかを制御できますが、QDirListing では、この処理を行うためのフラグが 1 セットしか用意されていません。

QDirIterator::IteratorFlags をQDirListing::IteratorFlags に移植するのは簡単です：

• QDirListing::IteratorFlag::Default は、QDirIterator::NoIteratorFlags
• QDirListing::IteratorFlag::FollowDirSymlinks は、QDirIterator::FollowSymlinks
• QDirListing::IteratorFlag::Recursive は以下と同等ですQDirIterator::Subdirectories

QDir::Filters をQDirListing::IteratorFlags に移植するのは、使用するQDir::Filters のビット単位の OR 結合の組み合わせによっては、より複雑になる可能性があります。

• デフォルトでは、QDirListing はディレクトリ、通常ファイル、シンボリックリンク、および特殊（その他）なファイルシステムエントリを一覧表示します。さまざまな QDirListing::IteratorFlag::Exclude* フラグを使用することで、エントリの種類に基づいて除外することができます。
• QDirのデフォルトのフィルタはQDir::AllEntries であり、これは以下と同等です:

  using F = QDirListing::IteratorFlag;
  QDirListing::IteratorFlags(F::ExcludeOther|F::ResolveSymlinks|F::IncludeDotAndDotDot);

• デフォルトでは、QDirListing は（Windows の）ドライブを一覧表示するため、QDir::Drives に対応する設定はありません。
• QDir::Readable、QDir::Writable 、QDir::Executable 、およびQDir::AllDirs ：QDirListing にはこれらに相当するフラグはありません。この機能が必要な場合は、range-forループを使用してエントリを反復処理し、必要に応じてフィルタリングを行ってください。

  QDirIterator dit(dirPath, QDir::AllEntries | QDir::Readable | QDir::Executable | QDir::NoDotAndDotDot);
  while (dit.hasNext()) {
      const QFileInfo fi = dit.nextFileInfo();
      fileNames.append(fi.fileName());
      ...
  }
  
  using F = QDirListing::IteratorFlags;
  for (const auto &dirEntry : QDirListing(dirPath, F::Default)) {
      const QFileInfo fi = dirEntry.fileInfo();
      // Filter based on readable and executable bits
      if (fi.isReadable() && fi.isExecutable()) {
          fileNames.append(dirEntry.fileName());
          ...
      }
  }

  // QDir::AllDirs causes dirs to always be listed regardless of `nameFilters`;
  // for example, to list ".so" files in a file dialog and still list all dirs:
  QDirIterator dit(dirPath, nameFilters, QDir::AllDirs | QDir::NoDotAndDotDot);
  while (dit.hasNext()) {
      const QFileInfo fi = dit.nextFileInfo();
      ...
  }
  
  // Equivalent code using QDirListing:
  using F = QDirListing::IteratorFlags;
  for (const auto &dirEntry : QDirListing(dirPath, F::Default)) {
      const QFileInfo fi = dirEntry.fileInfo();
      if (fi.isDir() || fi.fileName().endsWith(".so"_L1)) {
          ...
      }
  }

• QDirListing では、QDir::NoDot 、QDir::NoDotDot 、およびQDir::NoDotAndDotDot の動作が 1 つのフラグに統合されています。デフォルトでは、QDirListing は特別なエントリである. および.. を一覧表示しません。これらを一覧表示するには、QDirListing::IteratorFlag::IncludeDotAndDotDot を設定してください。

シンボリックリンク

デフォルトでは、QDirIterator はQDir::NoSymlinksが設定されていない限りシンボリックリンクを解決しますが、QDirListing はQDirListing::IteratorFlag::ResolveSymlinks が設定されていない限りシンボリックリンクを解決しません。 が設定されている場合、フィルタリングはシンボリックリンク自体ではなく、そのリンク先のタイプに基づいて行われます。たとえば、通常のファイルと、通常のファイルへのシンボリックリンクのみを一覧表示するには、QDirListing::IteratorFlag::FilesOnly と QDirListing::IteratorFlag::ResolveSymlinks を設定する必要があります。

// Symbolic links are resolved by default
QDirIterator dit(dirPath, QDir::Files | QDir::NoDotAndDotDot);
while (dit.hasNext()) {
    const QFileInfo fi = dit.nextFileInfo();
    fileNames.append(fi.fileName());
    ...
}

// To preserve the behavior of the code above, set ResolveSymlinks:
using F = QDirListing::IteratorFlags;
for (const auto &dirEntry : QDirListing(dirPath, F::FilesOnly | F::ResolveSymlinks)) {
    fileNames.append(dirEntry.fileName());
    ...
}

QDirListing::DirEntry

QDirListing::DirEntry は、QFileInfo のAPIの一部（例：fileName()、filePath()、exists()）を提供します。DirEntryのAPIの主な利点は、他の手段で必要な情報をすでに取得している場合、(かなり負荷の高い)stat() やlstat() の呼び出しを遅延させることができる点です。 たとえばLinuxでは、内部的にreaddir()を使用してディレクトリツリーを反復処理し、返される情報の一部としてエントリの名前とタイプを取得します。したがって、ファイル名のみが必要な場合は、QDirListing::DirEntry::fileInfo()の代わりにQDirListing::DirEntry::fileName()を使用してください（fileName()）。（QDirListing は内部でQFileInfo を構築し、必要に応じて透過的にそれを使用します）。