For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
describes an input iterator that sequences through the filenames in a directory, possibly descending into subdirectories recursively. For an iterator X, the expression *X evaluates to an object of class directory_entry that wraps the filename and anything known about its status.
For more information and code examples, see File System Navigation (C++).
The template class stores:
an object of type stack<pair<directory_iterator, path>>, called mystack here for the purposes of exposition, which represents the nest of directories to be sequenced
an object of type directory_entry called myentry here, which represents the current filename in the directory sequence
an object of type bool, called no_push here, which records whether recursive descent into subdirectories is disabled
an object of type directory_options, called myoptions here, which records the options established at construction
A default constructed object of type recursive_directory_entry has an end-of-sequence iterator at mystack.top().first and represents the end-of-sequence iterator.For example, given the directory abc with entries def (a directory), def/ghi, and jkl, the code:
for (recursive_directory_iterator next(path("abc")), end; next != end; ++next) visit(next->path());
will call visit with the arguments
path("abc/def/ghi") and path("abc/jkl").You can qualify sequencing through a directory subtree in two ways:
A directory symlink will be scanned only if you construct a recursive_directory_iterator with a directory_options argument whose value is directory_options::follow_directory_symlink.
If you call disable_recursion_pending then a subsequent directory encountered during an increment will not be recursively scanned.
int depth() const;
Returns mystack.size() - 1, so pval is at depth zero.
The member function stores true in no_push.
bool operator!=(const recursive_directory_iterator& right) const;
The member operator returns !(*this == right).
recursive_directory_iterator& operator=(const recursive_directory_iterator&) = default; recursive_directory_iterator& operator=(recursive_directory_iterator&&) noexcept = default;
The defaulted member assignment operators behave as expected.
bool operator==(const recursive_directory_iterator& right) const;
The member operator returns true only if both *this and right are end-of-sequence iterators or both are not end-of-sequence-iterators.
const directory_entry& operator*() const;
The member operator returns myentry.
const directory_entry * operator->() const;
recursive_directory_iterator& operator++(); recursive_directory_iterator& operator++(int);
The first member function calls increment(), then returns *this. The second member function makes a copy of the object, calls increment(), then returns the copy.
directory_options options() const;
If depth() == 0 the object becomes an end-of-sequence iterator. Otherwise, the member function terminates scanning of the current (deepest) directory and resumes at the next lower depth.
bool recursion_pending() const;
recursive_directory_iterator() noexcept; explicit recursive_directory_iterator(const path& pval); recursive_directory_iterator(const path& pval, error_code& ec) noexcept; recursive_directory_iterator(const path& pval, directory_options opts); recursive_directory_iterator(const path& pval, directory_options opts, error_code& ec) noexcept; recursive_directory_iterator(const recursive_directory_iterator&) = default; recursive_directory_iterator(recursive_directory_iterator&&) noexcept = default;
The first constructor produces an end-of-sequence iterator. The second and third constructors store false in no_push and directory_options::none in myoptions, then attempt to open and read pval as a directory. If successful, they initialize mystack and myentry to designate the first non-directory filename in the nested sequence; otherwise they produce an end-of-sequence iterator.
The fourth and fifth constructors behave the same as the second and third, except that they first store opts in myoptions. The defaulted construtors behave as expected.
recursive_directory_iterator& increment(error_code& ec) noexcept;
The function attempts to advance to the next filename in the nested sequence. If successful, it stores that filename in myentry; otherwise it produces an end-of-sequence iterator.