From 1885818461adfd20e47f03bc052c2adee4dda48b Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Tue, 12 Jul 2005 19:41:22 +0000 Subject: [PATCH] Use option 3 - iterator predicate functions. Document recently added functionality such as if_other(), basic_recursive_directory_iterator [SVN r30021] --- doc/convenience.htm | 109 ++++++++++-- doc/do-list.htm | 43 +---- doc/i18n.html | 11 +- doc/operations.htm | 121 ++++++-------- example/mbcopy.cpp | 4 +- example/simple_ls.cpp | 10 +- include/boost/filesystem/convenience.hpp | 23 ++- include/boost/filesystem/operations.hpp | 204 +++++++++-------------- test/operations_test.cpp | 54 +++--- test/wide_test.cpp | 4 +- 10 files changed, 291 insertions(+), 292 deletions(-) diff --git a/doc/convenience.htm b/doc/convenience.htm index 3bef4db..3c2319a 100644 --- a/doc/convenience.htm +++ b/doc/convenience.htm @@ -6,8 +6,6 @@ - - Boost Filesystem convenience.hpp Header @@ -16,20 +14,24 @@

boost/filesystem/convenience.hpp

+

Contents

+ +
+
Introduction
create_directories +
extension +
basename +
change_extension
+basic_recursive_directory_iterator
+ +

Introduction

+

Header convenience.hpp provides convenience functions that combine lower-level functions in useful ways.

-

Contents

+

The entire contents of the header is in namespace boost::filesystem.

-
-
create_directories -
extension -
basename -
change_extension -
- -

create_directories

+

create_directories

@@ -50,7 +52,7 @@ establishment of the postcondition.

-

extension

+

extension

@@ -75,7 +77,7 @@ discussed the ADS issue.
-

basename

+

basename

@@ -93,7 +95,7 @@ ending at the last dot (the dot is not included). Otherwise, returns
-

change_extension

+

change_extension

@@ -118,10 +120,85 @@ is to drop the precondition.

+

basic_recursive_directory_iterator

+ +
template< class Path >
+class basic_recursive_directory_iterator
+  : public boost::iterator_facade<
+      basic_recursive_directory_iterator<Path>, Path,
+      boost::single_pass_traversal_tag >
+{
+public:
+  typedef Path path_type;
+
+  basic_recursive_directory_iterator(){} // creates the "end" iterator
+
+  explicit basic_recursive_directory_iterator( const Path & dir_path );
+
+  int level() const;
+
+  void pop();
+  void no_push();
+
+  status_flags status( system_error_type * ec=0 ) const;
+  status_flags status( const symlink_t &, system_error_type * ec=0 ) const;
+
+  bool exists() const;
+  bool is_directory() const;
+  bool is_file() const;
+  bool is_other() const;
+  bool is_symlink() const;
+
+private:
+  int m_level; // for exposition only
+};
+
+typedef basic_recursive_directory_iterator<path> recursive_directory_iterator;
+typedef basic_recursive_directory_iterator<wpath> wrecursive_directory_iterator;
+ +

The behavior of basic_recursive_directory_iterator member functions is +the same as basic_directory_iterator +functions of the same name, except:

+ +

The issue of duplicates (caused by symlinks and hard links) should be +consider when using basic_recursive_directory_iterator. + Both duplicate detecting and non-detecting are needed, depending on the +application. Non-detecting is far + more efficient, but some apps will require duplicate detection.

+

When duplicate prevention is required, consider simply not following symlinks. +Use the no_push() function to avoid recursion into directories +reached by symlinks. If a more comprehensive solution is required, consider +these factors:

+ + +

Contributed by Beman Dawes

Revised -14 May, 2005

-

© Copyright Vladimir Prus, 2003

+12 July, 2005

+

© Copyright Beman Dawes, 2005
+© Copyright Vladimir Prus, 2003

Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at diff --git a/doc/do-list.htm b/doc/do-list.htm index b84d09a..9df3fbd 100644 --- a/doc/do-list.htm +++ b/doc/do-list.htm @@ -9,54 +9,13 @@ Do-list

Defer until after mini-review

-

Non-member functions

+

Other member functions

+ +

These member functions have the same behavior as the non-member operations +functions of the same name, except that they may rely on cached status +information. See performance note.

+ +

All have a precondition that the iterator not be the end iterator.

+ +

Operations non-member functions

-The non-member functions provide common operations on files and directories. +The operations non-member functions provide common operations on files and directories. They follow traditional practice of the C, and C++ standard libraries, except that they:

@@ -268,9 +264,7 @@ exposition, only the templated version of each non-member function is shown.

status

template<class Path>   status_flags status( const Path & ph, system_error_type * ec = 0 );
-template<class DirItr> status_flags status( const DirItr & it, system_error_type * ec = 0 );
-template<class Path>   status_flags status( const Path & ph, const symlink_t &, system_error_type * ec = 0 );
-template<class DirItr> status_flags status( const DirItr & it, const symlink_t &, system_error_type * ec = 0 );
+template<class Path> status_flags status( const Path & ph, const symlink_t &, system_error_type * ec = 0 );

Effects: