Edit

Share via

directory_iterator class

  • Article

Describes an input iterator that sequences through the filenames in a directory. For an iterator X, the expression *X evaluates to an object of class directory_entry that wraps the filename and anything known about its status.

The class stores an object of type path, called mydir here for the purposes of exposition, which represents the name of the directory to be sequenced, and an object of type directory_entry called myentry here, which represents the current filename in the directory sequence. A default constructed object of type directory_entry has an empty mydir pathname and represents the end-of-sequence iterator.

For example, given the directory abc with entries def and ghi, the code:

for (directory_iterator next(path("abc")), end; next != end; ++next) visit(next->path());

calls visit with the arguments path("abc/def") and path("abc/ghi").

For more information and code examples, see File System Navigation (C++).

Syntax

class directory_iterator;

Constructors

Constructor Description
directory_iterator Constructs an input iterator that sequences through the filenames in a directory.

Member functions

Member function Description
increment Attempts to advance to the next filename in the directory.

Operators

Operator Description
operator!= Returns !(*this == right).
operator= The defaulted member assignment operators behave as expected.
operator== Returns true only if both *this and right are end-of-sequence iterators or both aren't end-of-sequence-iterators.
operator* Returns myentry.
operator-> Returns &**this.
operator++ Calls increment(), then returns *this, or makes a copy of the object, calls increment(), then returns the copy.

Requirements

Header: <filesystem>

Namespace: std::filesystem

directory_iterator::directory_iterator

The first constructor produces an end-of-sequence iterator. The second and third constructors store pval in mydir, then attempt to open and read mydir as a directory. If successful, they store the first filename in the directory in myentry; otherwise they produce an end-of-sequence iterator.

The default constructor behaves as expected.

directory_iterator() noexcept;
explicit directory_iterator(const path& pval);

directory_iterator(const path& pval, error_code& ec) noexcept;
directory_iterator(const directory_iterator&) = default;
directory_iterator(directory_iterator&&) noexcept = default;

Parameters

pval
The stored file name path.

ec
The status error code.

directory_iterator
The stored object.

directory_iterator::increment

The function attempts to advance to the next filename in the directory. If successful, it stores that filename in myentry; otherwise it produces an end-of-sequence iterator.

directory_iterator& increment(error_code& ec) noexcept;

directory_iterator::operator!=

The member operator returns !(*this == right).

bool operator!=(const directory_iterator& right) const;

Parameters

right
The directory_iterator being compared to the directory_iterator.

directory_iterator::operator=

The defaulted member assignment operators behave as expected.

directory_iterator& operator=(const directory_iterator&) = default;
directory_iterator& operator=(directory_iterator&&) noexcept = default;

Parameters

right
The directory_iterator being copied into the directory_iterator.

directory_iterator::operator==

The member operator returns true only if both *this and right are end-of-sequence iterators or both aren't end-of-sequence-iterators.

bool operator==(const directory_iterator& right) const;

Parameters

right
The directory_iterator being compared to the directory_iterator.

directory_iterator::operator*

The member operator returns myentry.

const directory_entry& operator*() const;

directory_iterator::operator->

The member function returns &**this.

const directory_entry * operator->() const;

directory_iterator::operator++

The first member function calls increment(), then returns *this. The second member function makes a copy of the object, calls increment(), then returns the copy.

directory_iterator& operator++();
directory_iterator& operator++(int);

Parameters

int
The number of increments.

See also

<filesystem>
Header Files Reference
File System Navigation (C++)