Class recursive_directory

Class recursive_directory_iterator

boost::filesystem::recursive_directory_iterator — Objects of type recursive_directory_iterator provide standard library compliant iteration over the contents of a directory, including recursion into its sub-directories.

Synopsis

// In header: <boost/filesystem/directory.hpp>


class recursive_directory_iterator : public boost::iterator_facade< recursive_directory_iterator, directory_entry, boost::single_pass_traversal_tag >
{
public:

  // public member functions
  recursive_directory_iterator() noexcept;
  recursive_directory_iterator(path const &, directory_options, 
                               system::error_code &);
  recursive_directory_iterator(path const &, system::error_code &);
  recursive_directory_iterator(path const &, directory_options);
  explicit recursive_directory_iterator(path const &);
  recursive_directory_iterator(recursive_directory_iterator const &) = default;
  recursive_directory_iterator & 
  operator=(recursive_directory_iterator const &) = default;
  recursive_directory_iterator(recursive_directory_iterator &&) noexcept;
  recursive_directory_iterator & 
  operator=(recursive_directory_iterator &&) noexcept;
  recursive_directory_iterator & increment(system::error_code &) noexcept;
  recursive_directory_iterator & operator++();
  directory_entry const & operator*() const noexcept;
  const directory_entry * operator->() const noexcept;
  bool operator==(recursive_directory_iterator const &) const noexcept;
  bool operator!=(recursive_directory_iterator const &) const noexcept;
  int depth() const noexcept;
  bool recursion_pending() const noexcept;
  void disable_recursion_pending(bool = true) noexcept;
  void pop(system::error_code &) noexcept;
  void pop();
  file_status status() const;
  file_status symlink_status() const;
};

Description

The behavior of a recursive_directory_iterator is the same as a directory_iterator unless otherwise specified. The main differences are:

Incrementing a recursive_directory_iterator pointing to a directory causes that directory itself to be iterated over, as specified by the operator++ and increment functions.
When a recursive_directory_iterator reaches the end of the directory currently being iterated over, or when pop() is called, iteration depth is decremented, and iteration of the parent directory continues.

	Note
	Like `directory_iterator`, `recursive_directory_iterator` objects also maintain internal shared state, so the same caveats as for `directory_iterator` apply.

See Also: directory_iterator

`recursive_directory_iterator` public member functions

```
recursive_directory_iterator() noexcept;
```
Default constructor.
Effects: Constructs the end iterator.

recursive_directory_iterator(path const & p, directory_options opts, 
                             system::error_code & ec);

Constructs an iterator representing the first entry in the directory.

Effects:

Constructs an iterator representing the first entry in the directory p resolves to, if any; otherwise, the end iterator.

If opening the directory fails with a permission_denied error and (opts & directory_options::skip_permission_denied) != 0, constructs the end iterator and ignores the error.

For the overloads taking ec, an end iterator is constructed in case of error.

	Note
	To iterate over the current directory, use `recursive_directory_iterator(".")` rather than `recursive_directory_iterator("")`.

	Note
	By default, `recursive_directory_iterator` does not follow directory symlinks. To follow directory symlinks, specify `directory_options::follow_directory_symlink`.

Parameters:

`p`	Path to directory to iterate over.
`opts`	Directory iteration options. `directory_options::none` if not specified.
`ec`	Error code returned in case of failure.

Postconditions:

Unless the end iterator was constructed, *this points to the first entry and depth() == 0 && recursion_pending() == true.

```
recursive_directory_iterator(path const & p, system::error_code & ec);
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
recursive_directory_iterator(path const & p, directory_options opts);
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
explicit recursive_directory_iterator(path const & p);
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
recursive_directory_iterator(recursive_directory_iterator const & that) = default;
```
Copy constructor.
Effects:

If that is an end iterator, creates an end iterator. Otherwise, creates an iterator referring to the same shared state as that.

Parameters:

that

Iterator to copy from.

Postconditions:

*this == that.
```
recursive_directory_iterator & 
operator=(recursive_directory_iterator const & that) = default;
```
Copy assignment operator.
Effects:

If that is an end iterator, makes *this equal to end iterator. Otherwise, makes *this refer to the same shared state as that.

Parameters:

that

Iterator to copy from.

Postconditions:

*this == that.

Returns:

*this.
```
recursive_directory_iterator(recursive_directory_iterator && that) noexcept;
```
Move constructor.
Effects:

If that is an end iterator, creates an end iterator. Otherwise, creates an iterator referring to the same shared state as that.

Parameters:

that

Iterator to move from.

Postconditions:

*this is equal to the original value of that, that == recursive_directory_iterator().
```
recursive_directory_iterator & 
operator=(recursive_directory_iterator && that) noexcept;
```
Move assignment operator.
Effects:

If that is an end iterator, makes *this equal to end iterator. Otherwise, makes *this refer to the same shared state as that.

Parameters:

that

Iterator to move from.

Postconditions:

*this is equal to the original value of that, that == recursive_directory_iterator().

Returns:

*this.
```
recursive_directory_iterator & increment(system::error_code & ec) noexcept;
```
Advances the iterator to the next entry.
Effects:

As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators], except:
- if recursion_pending() && is_directory(this->status()) then directory is recursively iterated into and depth() is incremented.
- if opening the directory fails with a permission_denied error and (m_options & directory_options::skip_permission_denied) != 0, increments on the current level and ignores the error.
- if there are no more directory entries at this level then depth() is decremented and iteration of the parent directory resumes.
- If the operation completes with an error, then if (m_options & directory_options::pop_on_error) != 0, the iterator is left in a state as if after repeatedly calling pop() until it succeeds or the iterator becomes equal to an end iterator. Otherwise, the iterator is left equal to an end iterator.
Parameters:

ec

Error code returned in case of failure.

Postconditions:

recursion_pending() == true.

Returns:

*this
```
recursive_directory_iterator & operator++();
```
Advances the iterator to the next entry.
Effects:

Equivalent to calling increment(ec), where ec is an instance of system::error_code. Throws filesystem_error with ec if the call fails.

See Also: increment.

Returns:

*this.
```
directory_entry const & operator*() const noexcept;
```
Dereferences the iterator.

Returns:

The directory entry referenced by the iterator.
```
const directory_entry * operator->() const noexcept;
```
Indirection operator of the iterator.

Returns:

The directory entry referenced by the iterator.
```
bool operator==(recursive_directory_iterator const & that) const noexcept;
```
Compares two recursive directory iterators for equivalence.

Parameters:

that

Recursive directory iterator to compare with.

Returns:

true if both *this and that are end iterators or refer to the same shared state, otherwise false.
```
bool operator!=(recursive_directory_iterator const & that) const noexcept;
```
Compares two recursive directory iterators for inequivalence.

Parameters:

that

Recursive directory iterator to compare with.

Returns:

!(*this == that).
```
int depth() const noexcept;
```
Returns the depth of the current directory entry.
The top level directory with path to which the iterator was constructed has depth 0. Immediate subdirectories of the top level directory have depth 1, and so on.

Requires:

*this != recursive_directory_iterator().

Returns:

Current iteration depth.

bool recursion_pending() const noexcept;

Checks if recursion is pending.

Requires:	`*this != recursive_directory_iterator()`.
Returns:	`true` if `disable_recursion_pending(true)` has not been called after the prior construction or increment operation, otherwise `false`.

void disable_recursion_pending(bool value = true) noexcept;

Disables or enables recursion into the current directory entry.

Parameters:

value

Indicates whether the subsequent increment operation should attempt to recurse into subdirectory.

Requires:

*this != recursive_directory_iterator().

Postconditions:

recursion_pending() == value.

```
void pop(system::error_code & ec) noexcept;
```
Pops the current directory from the iteration stack.

Effects:

If depth() == 0, sets *this to recursive_directory_iterator(). Otherwise, decrements depth(), ceases iteration of the directory currently being iterated over, and continues iteration over the parent directory. If the operation completes with an error, then if directory_options::pop_on_error was specified in options on the iterator construction, the iterator is left in a state as if after repeatedly calling pop() until it succeeds or the iterator becomes equal to an end iterator. Otherwise, the iterator is left equal to an end iterator.

Parameters:

ec

Error code returned in case of failure.

Requires:

*this != recursive_directory_iterator().
```
void pop();
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
file_status status() const;
```
Returns file status of the current directory entry.

Note

Use iterator dereferencing operators instead, e.g. it->status().

See Also: status.

Returns:

(*this)->status().
```
file_status symlink_status() const;
```
Returns symlink file status of the current directory entry.

Note

Use iterator dereferencing operators instead, e.g. it->symlink_status().

See Also: symlink_status.

Returns:

(*this)->symlink_status().

	Note
	Use iterator dereferencing operators instead, e.g. `it->status()`.