cppdraft_translate/cppdraft/fs/class/rec/dir/itr.md

[fs.class.rec.dir.itr]

31 Input/output library [input.output]

31.12 File systems [filesystems]

31.12.12 Class recursive_directory_iterator [fs.class.rec.dir.itr]

31.12.12.1 General [fs.class.rec.dir.itr.general]

1

#

An object of type recursive_directory_iterator provides an iterator for a sequence of directory_entry elements representing the files in a directory or in an implementation-defined directory-like file type, and its subdirectories.

namespace std::filesystem {class recursive_directory_iterator {public:using iterator_category = input_iterator_tag; using value_type = directory_entry; using difference_type = ptrdiff_t; using pointer = const directory_entry*; using reference = const directory_entry&; // [fs.rec.dir.itr.members], constructors and destructor recursive_directory_iterator() noexcept; explicit recursive_directory_iterator(const path& p); recursive_directory_iterator(const path& p, directory_options options); recursive_directory_iterator(const path& p, directory_options options, error_code& ec); recursive_directory_iterator(const path& p, error_code& ec); recursive_directory_iterator(const recursive_directory_iterator& rhs); recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept; ~recursive_directory_iterator(); // [fs.rec.dir.itr.members], observers directory_options options() const; int depth() const; bool recursion_pending() const; const directory_entry& operator*() const; const directory_entry* operator->() const; // [fs.rec.dir.itr.members], modifiers recursive_directory_iterator&operator=(const recursive_directory_iterator& rhs); recursive_directory_iterator&operator=(recursive_directory_iterator&& rhs) noexcept;

recursive_directory_iterator& operator++(); recursive_directory_iterator& increment(error_code& ec); void pop(); void pop(error_code& ec); void disable_recursion_pending(); bool operator==(default_sentinel_t) const noexcept {return *this == recursive_directory_iterator(); }// other members as required by [input.iterators], input iterators};}

2

#

Calling options, depth, recursion_pending,pop or disable_recursion_pending on an iterator that is not dereferenceable results in undefined behavior.

3

#

The behavior of a recursive_directory_iterator is the same as a directory_iterator unless otherwise specified.

4

#

[Note 1:

If the directory structure being iterated over contains cycles then it is possible that the end iterator is unreachable.

— end note]

31.12.12.2 Members [fs.rec.dir.itr.members]

🔗

recursive_directory_iterator() noexcept;

1

#

Effects: Constructs the end iterator.

🔗

explicit recursive_directory_iterator(const path& p); recursive_directory_iterator(const path& p, directory_options options); recursive_directory_iterator(const path& p, directory_options options, error_code& ec); recursive_directory_iterator(const path& p, error_code& ec);

2

#

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

However, if(options & directory_options::skip_permission_denied) != directory_options::none and construction encounters an error indicating that permission to access p is denied, constructs the end iterator and does not report an error.

3

#

Postconditions: options() == options for the signatures with adirectory_options argument, otherwise options() == directory_options​::​none.

4

#

Throws: As specified in [fs.err.report].

5

#

[Note 1:

Use recursive_directory_iterator(".") rather than recursive_directory_iterator("") to iterate over the current directory.

— end note]

6

#

[Note 2:

By default, recursive_directory_iterator does not follow directory symlinks.

To follow directory symlinks, specify options asdirectory_options​::​follow_directory_symlink.

— end note]

🔗

recursive_directory_iterator(const recursive_directory_iterator& rhs);

7

#

Postconditions:

• (7.1)

options() == rhs.options()

• (7.2)

depth() == rhs.depth()

• (7.3)

recursion_pending() == rhs.recursion_pending()

🔗

recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;

8

#

Postconditions: options(), depth(), and recursion_pending() have the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call.

🔗

recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);

9

#

Effects: If *this and rhs are the same object, the member has no effect.

10

#

Postconditions:

• (10.1)

options() == rhs.options()

• (10.2)

depth() == rhs.depth()

• (10.3)

recursion_pending() == rhs.recursion_pending()

11

#

Returns: *this.

🔗

recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;

12

#

Effects: If *this and rhs are the same object, the member has no effect.

13

#

Postconditions: options(), depth(), and recursion_pending() have the values that rhs.options(),rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call.

14

#

Returns: *this.

🔗

directory_options options() const;

15

#

Returns: The value of the argument passed to the constructor for theoptions parameter, if present, otherwisedirectory_options​::​none.

16

#

Throws: Nothing.

🔗

int depth() const;

17

#

Returns: The current depth of the directory tree being traversed.

[Note 3:

The initial directory is depth 0, its immediate subdirectories are depth 1, and so forth.

— end note]

18

#

Throws: Nothing.

🔗

bool recursion_pending() const;

19

#

Returns: true if disable_recursion_pending() has not been called subsequent to the prior construction or increment operation, otherwise false.

20

#

Throws: Nothing.

🔗

recursive_directory_iterator& operator++(); recursive_directory_iterator& increment(error_code& ec);

21

#

Effects: As specified for the prefix increment operation ofInput iterators, except that:

• (21.1)

If there are no more entries at the current depth, then if depth() != 0 iteration over the parent directory resumes; otherwise *this = recursive_directory_iterator().

• (21.2)

Otherwise ifrecursion_pending() && is_directory((*this)->status()) &&(!is_symlink((*this)->symlink_status()) ||(options() & directory_options::follow_directory_symlink) != directory_options::none) then either directory (*this)->path() is recursively iterated into or, if(options() & directory_options::skip_permission_denied) != directory_options::none and an error occurs indicating that permission to access directory (*this)->path() is denied, then directory (*this)->path() is treated as an empty directory and no error is reported.

22

#

Returns: *this.

23

#

Throws: As specified in [fs.err.report].

🔗

void pop(); void pop(error_code& ec);

24

#

Effects: If depth() == 0, set *this to recursive_directory_iterator().

Otherwise, cease iteration of the directory currently being iterated over, and continue iteration over the parent directory.

25

#

Throws: As specified in [fs.err.report].

26

#

Remarks: Any copies of the previous value of *this are no longer required to be dereferenceable nor to be in the domain of ==.

🔗

void disable_recursion_pending();

27

#

Postconditions: recursion_pending() == false.

28

#

[Note 4:

disable_recursion_pending() is used to prevent unwanted recursion into a directory.

— end note]

31.12.12.3 Non-member functions [fs.rec.dir.itr.nonmembers]

1

#

These functions enable use of recursive_directory_iterator with range-based for statements.

🔗

recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;

2

#

Returns: iter.

🔗

recursive_directory_iterator end(recursive_directory_iterator) noexcept;

3

#

Returns: recursive_directory_iterator().