QDirListing: improve the API docs
Change-Id: I27bfc958f278b8e450d0e67b15bcd0dc68476027 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
This commit is contained in:
parent
1c43f2fba9
commit
f26ada15a7
@ -25,12 +25,11 @@
|
|||||||
\snippet code/src_corelib_io_qdirlisting.cpp 1
|
\snippet code/src_corelib_io_qdirlisting.cpp 1
|
||||||
|
|
||||||
Iterators constructed by QDirListing (QDirListing::const_iterator) are
|
Iterators constructed by QDirListing (QDirListing::const_iterator) are
|
||||||
forward-only (you cannot iterate directories in reverse order) and don't
|
forward-only, single-pass iterators, that don't allow random access. They
|
||||||
allow random access. They can be used in ranged-for loops (or with STL
|
can be used in ranged-for loops (or with STL alogrithms that don't
|
||||||
alogrithms that don't require random access iterators). Dereferencing
|
require random access iterators). Dereferencing a valid iterator returns
|
||||||
a valid iterator returns a QDirListing::DirEntry object. The (c)end()
|
a QDirListing::DirEntry object. The (c)end() iterator marks the end of
|
||||||
iterator marks the end of the iteration. Dereferencing the end iterator
|
the iteration. Dereferencing the end iterator is undefined behavior.
|
||||||
is undefiend behavior.
|
|
||||||
|
|
||||||
QDirListing::DirEntry offers a subset of QFileInfo's API (for example,
|
QDirListing::DirEntry offers a subset of QFileInfo's API (for example,
|
||||||
fileName(), filePath(), exists()). Internally, DirEntry only constructs
|
fileName(), filePath(), exists()). Internally, DirEntry only constructs
|
||||||
@ -499,12 +498,25 @@ QString QDirListing::iteratorPath() const
|
|||||||
\fn QDirListing::const_iterator QDirListing::end() const
|
\fn QDirListing::const_iterator QDirListing::end() const
|
||||||
\fn QDirListing::const_iterator QDirListing::cend() const
|
\fn QDirListing::const_iterator QDirListing::cend() const
|
||||||
|
|
||||||
begin()/cbegin() returns a QDirListing::const_iterator that enables
|
(c)begin() returns a QDirListing::const_iterator that can be used to
|
||||||
iterating over directory entries using a ranged-for loop; dereferencing
|
iterate over directory entries.
|
||||||
this iterator returns a \c{const QFileInfo &}.
|
|
||||||
|
|
||||||
end()/cend() return a sentinel const_iterator that signals the end of
|
\list
|
||||||
the iteration. Dereferencing this iterator is undefined behavior.
|
\li This is a forward-only, single-pass iterator (you cannot iterate
|
||||||
|
directory entries in reverse order)
|
||||||
|
\li Doesn't allow random access
|
||||||
|
\li Can be used in ranged-for loops; or with STL algorithms that don't
|
||||||
|
require random access iterators
|
||||||
|
\li Dereferencing a valid iterator returns a \c{const DirEntry &}
|
||||||
|
\li (c)end() returns a sentinel-like const_iterator that signals the
|
||||||
|
end of the iteration. Dereferencing the end() iterator is undefined
|
||||||
|
behavior
|
||||||
|
\li Each time (c)begin() is called on the same QDirListing object,
|
||||||
|
the internal state is reset and the iteration starts anew
|
||||||
|
\endlist
|
||||||
|
|
||||||
|
(Some of the above restrictions are dictated by the underlying system
|
||||||
|
library functions' implementation).
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
\snippet code/src_corelib_io_qdirlisting.cpp 0
|
\snippet code/src_corelib_io_qdirlisting.cpp 0
|
||||||
@ -512,10 +524,6 @@ QString QDirListing::iteratorPath() const
|
|||||||
Here's how to find and read all files filtered by name, recursively:
|
Here's how to find and read all files filtered by name, recursively:
|
||||||
\snippet code/src_corelib_io_qdirlisting.cpp 1
|
\snippet code/src_corelib_io_qdirlisting.cpp 1
|
||||||
|
|
||||||
\note This is a forward-only iterator, every time begin()/cbegin() is
|
|
||||||
called (on the same QDirListing object), the internal state is reset and
|
|
||||||
the iteration starts anew.
|
|
||||||
|
|
||||||
\sa fileInfo(), fileName(), filePath()
|
\sa fileInfo(), fileName(), filePath()
|
||||||
*/
|
*/
|
||||||
QDirListing::const_iterator QDirListing::begin() const
|
QDirListing::const_iterator QDirListing::begin() const
|
||||||
|
Loading…
x
Reference in New Issue
Block a user