recursive_directory_iterator Class

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++).

Syntax

class recursive_directory_iterator;

Remarks

The class template stores:

1. 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

2. an object of type directory_entry called myentry here, which represents the current filename in the directory sequence

3. an object of type bool, called no_push here, which records whether recursive descent into subdirectories is disabled

4. 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:

1. 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.

2. If you call disable_recursion_pending, a subsequent directory encountered during an increment won't be recursively scanned.

Constructors

Constructor	Description
recursive_directory_iterator	Constructs a recursive_directory_iterator.

Member functions

Member function	Description
depth	Returns mystack.size() - 1, so pval is at depth zero.
disable_recursion_pending	Stores true in no_push.
increment	Advances to the next filename in sequence.
options	Returns myoptions.
pop	Returns the next object.
recursion_pending	Returns !no_push.

Operators

Operator	Description
operator!=	Returns !(*this == right).
operator=	The defaulted member assignment operators behave as expected.
operator==	Returns true only if both *this and right are end-of-sequence iterators or both aren't end-of-sequence-iterators.
operator*	Returns myentry.
operator->	Returns &**this.
operator++	Increments the recursive_directory_iterator.

Requirements

Header: <filesystem>

Namespace: std::tr2::sys

recursive_directory_iterator::depth

Returns mystack.size() - 1, so pval is at depth zero.

int depth() const;

recursive_directory_iterator::disable_recursion_pending

Stores true in no_push.

void disable_recursion_pending();

recursive_directory_iterator::increment

Advances to the next filename in sequence.

recursive_directory_iterator& increment(error_code& ec) noexcept;

Parameters

ec
Specified error code.

Remarks

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.

recursive_directory_iterator::operator!=

Returns !(*this == right).

bool operator!=(const recursive_directory_iterator& right) const;

Parameters

right
The recursive_directory_iterator for comparison.

recursive_directory_iterator::operator=

The defaulted member assignment operators behave as expected.

recursive_directory_iterator& operator=(const recursive_directory_iterator&) = default;
recursive_directory_iterator& operator=(recursive_directory_iterator&&) noexcept = default;

Parameters

recursive_directory_iterator
The recursive_directory_iterator being copied into the recursive_directory_iterator.

recursive_directory_iterator::operator==

Returns true only if both *this and right are end-of-sequence iterators or both aren't end-of-sequence-iterators.

bool operator==(const recursive_directory_iterator& right) const;

Parameters

right
The recursive_directory_iterator for comparison.

recursive_directory_iterator::operator*

Returns myentry.

const directory_entry& operator*() const;

recursive_directory_iterator::operator->

Returns &**this.

const directory_entry * operator->() const;

recursive_directory_iterator::operator++

Increments the recursive_directory_iterator.

recursive_directory_iterator& operator++();

recursive_directory_iterator& operator++(int);

Parameters

int
The specified increment.

Remarks

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.

recursive_directory_iterator::options

Returns myoptions.

directory_options options() const;

recursive_directory_iterator::pop

Returns the next object.

void pop();

Remarks

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.

recursive_directory_iterator::recursion_pending

Returns !no_push.

bool recursion_pending() const;

recursive_directory_iterator::recursive_directory_iterator

Constructs a recursive_directory_iterator.

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;

Parameters

pval
The specified path.

error_code
The specified error code.

opts
The specified directory options.

recursive_directory_iterator
The recursive_directory_iterator of which the constructed recursive_directory_iterator is to be a copy.

Remarks

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 default constructor behaves as expected.

See also

Header Files Reference
<filesystem>
File System Navigation (C++)