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

NAME
     std::filesystem::directory_iterator - std::filesystem::directory_iterator

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

	directory_iterator  is	a LegacyInputIterator that iterates over the di-
     rectory_entry
	elements of a directory (but does not visit the subdirectories). The it-
     eration order
	is unspecified, except that each directory entry is visited  only  once.
     The special
	pathnames dot and dot-dot are skipped.

	If  the directory_iterator reports an error or is advanced past the last
     directory
	entry, it becomes equal to the default-constructed iterator, also  known
     as the end
	iterator.  Two	end  iterators are always equal, dereferencing or incre-
     menting the end
	iterator is undefined behavior.

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

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 directory iterator
		      (public member function)
	destructor    default destructor
		      (public member function)
	operator=     assigns contents
		      (public member function)
	operator*     accesses the pointed-to entry
	operator->    (public member function)
	increment     advances to the next entry
	operator++    (public member function)

Non-member functions
	begin(std::filesystem::directory_iterator) range-based for loop support
	end(std::filesystem::directory_iterator)   (function)
	(C++17)

	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<>
     (since
	inline				 constexpr			    bool
     C++20)
	    enable_borrowed_range<std::filesystem::directory_iterator> = true;

	}
	namespace std::ranges {

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

	}

	These specializations for directory_iterator make  it  a  borrowed_range
     and a view.

Notes
	Many  low-level OS APIs for directory traversal retrieve file attributes
     along with
	the next directory entry. The  constructors  and  the  non-const  member
     functions of
	std::filesystem::directory_iterator  store  these attributes, if any, in
     the
	pointed-to std::filesystem::directory_entry without calling
	directory_entry::refresh, which makes it possible to examine the attrib-
     utes of the
	directory entries as they are being iterated over, without making  addi-
     tional system
	calls.

Example
     // Run this code

      #include <algorithm>
      #include <filesystem>
      #include <fstream>
      #include <iostream>

      int main()
      {
	  const std::filesystem::path sandbox{"sandbox"};
	  std::filesystem::create_directories(sandbox/"dir1"/"dir2");
	  std::ofstream{sandbox/"file1.txt"};
	  std::ofstream{sandbox/"file2.txt"};

	  std::cout << "directory_iterator:\n";
	  // directory_iterator can be iterated using a range-for loop
	  for (auto const& dir_entry : std::filesystem::directory_iterator{sand-
     box})
	      std::cout << dir_entry.path() << '\n';

	  std::cout << "\ndirectory_iterator as a range:\n";
	  // directory_iterator behaves as a range in other ways, too
	  std::ranges::for_each(
	      std::filesystem::directory_iterator{sandbox},
	      [](const auto& dir_entry) { std::cout << dir_entry << '\n'; });

	  std::cout << "\nrecursive_directory_iterator:\n";
	  for  (auto const& dir_entry : std::filesystem::recursive_directory_it-
     erator{sandbox})
	      std::cout << dir_entry << '\n';

	  // delete the sandbox dir and all contents within it,  including  sub-
     dirs
	  std::filesystem::remove_all(sandbox);
      }

Possible output:
      directory_iterator:
      "sandbox/file2.txt"
      "sandbox/file1.txt"
      "sandbox/dir1"

      directory_iterator as a range:
      "sandbox/file2.txt"
      "sandbox/file1.txt"
      "sandbox/dir1"

      recursive_directory_iterator:
      "sandbox/file2.txt"
      "sandbox/file1.txt"
      "sandbox/dir1"
      "sandbox/dir1/dir2"

	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	    directory_iterator was neither a  borrowed_range  it
     is both
			    nor a view

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

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