std::experi...ion_pending(3)

Okay bestie, welcome to std::experi...ion_pending(3) from the C++ Standard Libary manual — yes, “Libary,” that’s literally how it’s spelled in the header, and we’re keeping the facts exactly as they are 💅.

✨ NAME ✨

• std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending
• std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending

Yes, the NAME section lists the whole mouthful twice. The original is committed to the bit, and so am I 🎀.

🌸 Synopsis 🌸

void disable_recursion_pending();  (filesystem TS)

🦋 DESCRIPTION 🦋

This one disables recursion to the currently referred subdirectory, if any. Slay.

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 — the page says “directly,” and honestly? iconic typo behavior — even if it is currently referring to a subdirectory that hasn’t been visited.

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.

🚨 UB ALERT: the behavior is undefined if *this is the end iterator. Do not do that, bestie. No cap, that’s the dangerous one. 💀

💜 Parameters 💜

(none) — literally none.

🎀 Return value 🎀

(none) — it gives you nothing back, and that’s valid.

😭 Exceptions 😭

May throw implementation-defined exceptions.

🔥 Example 🔥

// Run this code

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

int main()
{
    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");
    for (auto i = fs::recursive_directory_iterator("sandbox");
             i != fs::recursive_directory_iterator(); ++i)
    {
        std::cout << std::string(i.depth(), ' ') << *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");
}

🍓 Output 🍓

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

👑 Category 👑

• Noindexed pages

---

Source/version and date vibes: http://cppreference.com, 2024.06.10, page std::experi...ion_pending(3). Byeee, bestie 🎀💖