std::filesy...ion_pending(3)

💖 NAME 💖

okay so bestie, welcome to the manpage for std::filesystem::recursive_directory_iterator::disable_recursion_pending, from the C++ Standard Libary manual — yes, that's literally how the header spells it, missing r and all 💀. The header also shortens the page name to std::filesy...ion_pending(3), which is giving "we ran out of room but make it fashion." The NAME section is the same long gorgeous name, a dash, and the same long gorgeous name again, because why say it once when you can say it twice? 💅

std::filesystem::recursive_directory_iterator::disable_recursion_pending
-
std::filesystem::recursive_directory_iterator::disable_recursion_pending

---

✨ Synopsis ✨

Since: C++17 🎀

The signature is exactly this, no cap:

void disable_recursion_pending();

It disables recursion to the currently referred subdirectory, if any — like, if the iterator is looking at a subdir and you're like "nope, not today," this is your move. 🫶

The call modifies the pending recursion flag on the iterator in such a way that the next time increment is called, the iterator will advance within the current directory even if it is currently referring to a subdirectory that hasn't been visited. That's the whole point, bestie: skip the descent, keep it moving. ✨

The status of the pending recursion flag can be queried with recursion_pending(), which is false after this call. It is reset back to true after increment, and its initial value is also true. So yeah, the flag starts true, gets turned false by this call, and then increment brings it back to true. Little flag, big main-character energy. 🌈

⚠️ The behavior is undefined if *this is the end iterator. That's UB, bestie — not cute, not safe, do not do it. 😭

---

🧸 Parameters 🧸

(none) — literally no parameters. Slay. 💅

---

💫 Return value 💫

(none) — it returns nothing. It's a void situation, and honestly that's fine. 🎀

---

🫧 Exceptions 🫧

May throw implementation-defined exceptions. So like, your implementation gets to decide the exception drama. 🙈

---

🌈 Example 🌈

The original literally says // Run this code right before the code, so here's that exact code, bestie:

        #include <cstdlib>
        #include <filesystem>
        #include <fstream>
        #include <iostream>
        #include <string>
        namespace fs = std::filesystem;

        int main()
        {
            fs::current_path(fs::temp_directory_path());
            fs::create_directories("sandbox/a/b/c");
            fs::create_directories("sandbox/a/b/d/e");
            std::ofstream("sandbox/a/b/file1.txt");
            fs::create_symlink("a", "sandbox/syma");
            std::system("tree sandbox");
            for (auto i = fs::recursive_directory_iterator("sandbox");
                 i != fs::recursive_directory_iterator();
                 ++i)
            {
                std::cout << std::string(i.depth() * 2, ' ') << *i;
                if (fs::is_symlink(i->symlink_status()))
                    std::cout << " -> " << fs::read_symlink(*i);
                std::cout << '\n';

                // do not descend into "b"
                if (i->path().filename() == "b")
                    i.disable_recursion_pending();
            }
            fs::remove_all("sandbox");
        }

---

🦋 Possible output 🦋

        sandbox
        ├── a
        │   └── b
        │       ├── c
        │       ├── d
        │       │   └── e
        │       └── file1.txt
        └── syma -> a

        "sandbox/a"
          "sandbox/a/b"
        "sandbox/syma" -> "a"

---

🔍 See also 🔍

• recursion_pending — checks whether the recursion is disabled for the current directory (public member function). 👀
• increment — advances to the next entry. ➡️
• operator++ — (public member function). ✨

---

That's the whole page, bestie. mwah 💋 — source: http://cppreference.com, dated 2024.06.10; the footer also re-stamps std::filesy...ion_pending(3). 💖✨