mozilla
Your Search Results

    OS.File.DirectoryIterator for workers

    This article is in need of a technical review.

    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

    Document Tags and Contributors

    Contributors to this page: teoli, Yoric, AmrEldib
    Last updated by: teoli,