std::filesy...operator++,(3)

✨ NAME ✨

okay so this is the std::filesy...operator++,(3) page from the C++ Standard Libary (yes, “Libary” is literally in the header — we love a typo moment 💀). The NAME line is std::filesystem::recursive_directory_iterator::operator++, — then a -, then std::filesystem::recursive_directory_iterator::operator++, again. It’s giving “two icons, same name” ✨.

🦋 Synopsis 🦋

recursive_directory_iterator& operator++();                     (1)
recursive_directory_iterator& increment( std::error_code& ec ); (2)

Both overloads are (since C++17). Highkey important. These advance the iterator to the next entry, and all copies of the previous value of *this get invalidated — so don’t go using stale copies after, bestie 😭.

When the current directory runs out of entries, iteration resumes over the parent directory. Rinse and repeat if the parent directory has no sibling entries that can to be iterated on (yes, that is the page’s wording, not mine 🫠). When you hit the parent of the whole directory hierarchy that has been recursively iterated on — as in, there are no candidate entries at depth() == 0 — *this is set to an end iterator. That’s the end, literally.

Otherwise, if *this refers to a directory, it gets iterated into only when these conditions hit:

• disable_recursion_pending() has not been called before this increment, i.e. recursion_pending() == true.
• The directory is not a symlink or following symlinks is enabled, i.e., at least one of the following is true:
  • !is_symlink((*this)->symlink_status()).
  • (options() & directory_options::follow_directory_symlink) != directory_options::none)

🎀 Parameters 🎀

• ec — error code to store the error status to.

💖 Return value 💖

*this — that’s the whole vibe.

😭 Exceptions 😭

• Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails.

1. Throws std::filesystem::filesystem_error on underlying OS API errors, constructed with the OS error code as the error code argument.
2. Sets a std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.

🌸 Example 🌸

This section is incomplete Reason: no example

not me crying over the missing example 😭

🍓 Defect reports 🍓

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR LWG 3013 — applied to C++17. Behavior as published: the error_code overload was marked noexcept but can allocate memory. Correct behavior: noexcept removed. 💅

🧚 Category 🧚

• Todo no example

xoxo, your Unix bestie 💅 — footer flex: source/version http://cppreference.com, date 2024.06.10, page id std::filesy...operator++,(3). 🫶