This document presents the mechanisms for walking the contents of a directory from a worker thread. For other uses of OS.File and OS.File.DirectoryIterator, please see the main document on OS.File.
Using OS.File.DirectoryIterator
Example: Finding the subdirectories of a directory using an iterator
The following snippet walks through the content of a directory, selecting subdirectories:
let iterator = new OS.File.DirectoryIterator(somePath);
try {
for (let entry in iterator) {
if (entry.isDir) {
// entry is a directory
}
}
} finally {
iterator.close();
}
Or a variant using array comprehension:
let iterator = new OS.File.DirectoryIterator(somePath);
try {
return [entry for (entry in iterator) if (entry.isDir) ];
} finally {
iterator.close();
}
Example: Sorting files by last modification date
The following takes advantage of feature detection to minimize file I/O:
let iterator = new OS.File.DirectoryIterator(somePath);
try {
let entries;
if ("winCreationDate" in OS.File.DirectoryIterator.Entry.prototype) {
// Under Windows, additional information allow us to sort files immediately
// without having to perform additional I/O.
entries = [{entry: entry, creationDate: entry.winCreationDate} for (entry in iterator)];
} else {
// Under other OSes, we need to call OS.File.stat
entries = [{entry: entry, creationDate: OS.File.stat(entry.path).creationDate} for (entry in iterator)];
}
// Finally, sort the array
return entries.sort(function compare(a, b) {
return a.creationDate - b.creationDate;
});
}
Instances of OS.File.DirectoryIterator
General remark
All instances of worker thread OS.File.DirectoryIterator can be iterated using array comprehension. This is generally the best way to walk through a directory.
Instances of OS.File.DirectoryIterator uses valuable system resources – typically the same resources as files. There is a limit to the total number of files and directory iterators that can be open at any given time. Therefore, you should make sure that these resources are released as early as possible. To do this, you should use method close().
Constructor
OS.File.DirectoryIterator( in string path, [optional] in object options ) throws OS.File.Error
Arguments
- path
- The full path to a directory.
- options
- An object that may contain the following fields:
- winPattern
-
(ignored on non-Windows platforms) This option accepts a pattern such as
"*.exe"or"*.txt". The iterator will only display items whose name matches this pattern.
Method overview
| void close() |
| void forEach(in function callback) |
| Array nextBatch([optional] in number length) |
| Entry next() |
Methods
close()
Close the iterator, releasing the system resources it uses.
void close() throws OS.File.Error
You should always call this method once you are done with an iterator. Calling this method several times is harmless. Calling this method while iterating through the directory is harmless but will stop the iteration.
forEach()
Walk through the iterator.
void forEach( in function callback ) throws OS.File.Error
Arguments
- callback
- A function. It will be applied to each entry in the directory successively, with the following arguments:
- entry
- An instance of OS.File.DirectoryIterator.Entry.
- index
- The index of the entry in the enumeration.
- iterator
-
The iterator itself. You may stop the iteration by calling
iterator.close().
nextBatch()
Return several entries at once.
array nextBatch( [optional] in number entries ) throws OS.File.Error
Arguments
- entries
- The number of entries to return at once. If unspecified, all entries.
Returns
An array containing entries entries, or less if there are not enough entries left in the directory. Once iteration is complete, calls to nextBatch return the empty array.
next()
Return the next entry in the directory.
Entry next() throws OS.File.Error, StopIteration
Returns
The next entry in the directory.
Throws
- OS.File.Error
- In case of file error
- StopIteration
- If the method is called after the last entry has been returned