home | help 
std::filesy...ory_iterator(3)  C++ Standard Libary std::filesy...ory_iterator(3)

NAME
     std::filesystem::recursive_directory_iterator   -	 std::filesystem::recur-
     sive_directory_iterator

Synopsis
	Defined in header <filesystem>
	class recursive_directory_iterator;  (since C++17)

	recursive_directory_iterator is a LegacyInputIterator that iterates over
     the
	directory_entry elements of a directory, and, recursively, over the  en-
     tries of all
	subdirectories. The iteration order is unspecified, except that each di-
     rectory entry
	is visited only once.

	By default, symlinks are not followed, but this can be enabled by speci-
     fying the
	directory option follow_directory_symlink at construction time.

	The special pathnames dot and dot-dot are skipped.

	If the recursive_directory_iterator reports an error or is advanced past
     the last
	directory entry of the top-level directory, it becomes equal to the
	default-constructed  iterator,	also  known as the end iterator. Two end
     iterators are
	always equal, dereferencing or incrementing the end  iterator  is  unde-
     fined behavior.

	If a file or a directory is deleted or added to the directory tree after
     the
	recursive directory iterator has been created, it is unspecified whether
     the change
	would be observed through the iterator.

	If  the directory structure contains cycles, the end iterator may be un-
     reachable.

Member types
	Member type	  Definition
	value_type	  std::filesystem::directory_entry
	difference_type   std::ptrdiff_t
	pointer 	  const std::filesystem::directory_entry*
	reference	  const std::filesystem::directory_entry&
	iterator_category std::input_iterator_tag

Member functions
	constructor		  constructs a recursive directory iterator
				  (public member function)
	destructor		  default destructor
				  (public member function)

Observers
	operator*		  accesses the pointed-to entry
	operator->		  (public member function)
				  returns the currently active options that  af-
     fect the
	options 		  iteration
				  (public member function)
	depth			  returns the current recursion depth
				  (public member function)
				  checks  whether  the recursion is disabled for
     the current
	recursion_pending	  directory
				  (public member function)

Modifiers
	operator=		  assigns contents
				  (public member function)
	increment		  advances to the next entry
	operator++		  (public member function)
	pop			  moves the iterator one level up in the  direc-
     tory hierarchy
				  (public member function)
	disable_recursion_pending disables recursion until the next increment
				  (public member function)

Non-member functions
	begin(std::filesystem::recursive_directory_iterator)   range-based   for
     loop support
	end(std::filesystem::recursive_directory_iterator)   (function)

	Additionally,
	operator== and operator!= are
	(until C++20)
	operator== is
	(since C++20) provided as required by LegacyInputIterator.

	It is unspecified
	whether operator!= is provided because it can be synthesized from opera-
     tor==, and
	(since C++20) whether an equality operator is a member or non-member.

	Helper templates

	namespace std::ranges {

	template<>
	inline				constexpr			    bool
     (since
	    enable_borrowed_range<std::filesystem::recursive_directory_iterator>
     =	 C++20)
	true;

	}
	namespace std::ranges {

	template<>
     (since
	inline				 constexpr			    bool
     C++20)
	    enable_view<std::filesystem::recursive_directory_iterator> = true;

	}

	These specializations for recursive_directory_iterator make  it  a  bor-
     rowed_range and
	a view.

Notes
	A   recursive_directory_iterator  typically  holds  a  reference-counted
     pointer (to
	satisfy shallow-copy semantics of LegacyInputIterator) to an implementa-
     tion object,
	which holds:

	  * a container (such as std::vector) of non-recursive	directory_itera-
     tors that
	    forms the recursion stack,
	  * the recursion depth counter (accessible with depth()),
	  *  the  directory  options  used  at construction (accessible with op-
     tions()),
	  * the pending recursion flag (accessible with recursion_pending(), may
     be combined
	    with the directory options to save space).

Example
     // Run this code

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

      int main()
      {
	  std::filesystem::current_path(std::filesystem::temp_directory_path());
	  std::filesystem::create_directories("sandbox/a/b");
	  std::ofstream("sandbox/file1.txt");
	  std::filesystem::create_symlink("a", "sandbox/syma");

	  // Iterate over the std::filesystem::directory_entry elements  explic-
     itly
	  auto entry_length{3UZ};
	  for (const fs::directory_entry& dir_entry :
		  fs::recursive_directory_iterator("sandbox"))
	  {
	      std::cout << dir_entry << '\n';
	      if (auto l{dir_entry.path().string().length()}; entry_length < l)
		  entry_length = l;
	  }
	  std::cout << std::string(entry_length + 2, '-') << '\n';

	  //  Iterate  over  the std::filesystem::directory_entry elements using
     `auto`
	  for (auto const& dir_entry  :  fs::recursive_directory_iterator("sand-
     box"))
	      std::cout << dir_entry << '\n';

	  std::filesystem::remove_all("sandbox");
      }

Possible output:
      "sandbox/syma"
      "sandbox/file1.txt"
      "sandbox/a"
      "sandbox/a/b"
      -------------------
      "sandbox/syma"
      "sandbox/file1.txt"
      "sandbox/a"
      "sandbox/a/b"

	Defect reports

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

	   DR	 Applied to		 Behavior as published		    Cor-
     rect behavior
	LWG 3480 C++20	    recursive_directory_iterator was neither  a       it
     is both
			    borrowed_range nor a view

See also
	directory_iterator an iterator to the contents of the directory
	(C++17) 	   (class)
	directory_entry    a directory entry
	(C++17) 	   (class)
	directory_options  options for iterating directory contents
	(C++17) 	   (enum)

http://cppreference.com 	   2024.06.10	   std::filesy...ory_iterator(3)
home | help