E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

gdirectory.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 Graeme Walker <graeme_walker@users.sourceforge.net>
3 //
4 // This program is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // This program is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with this program. If not, see <http://www.gnu.org/licenses/>.
16 // ===
17 ///
18 /// \file gdirectory.h
19 ///
20
21 #ifndef G_DIRECTORY_H
22 #define G_DIRECTORY_H
23
24 #include "gdef.h"
25 #include "gpath.h"
26 #include "gexception.h"
27 #include <string>
28 #include <vector>
29 #include <list>
30 #include <sys/types.h>
31
32 namespace G
33 {
34 class DirectoryIteratorImp ;
35 class Directory ;
36 class DirectoryIterator ;
37 class DirectoryList ;
38 }
39
40 /// \class G::Directory
41 /// An encapsulation of a file system directory that allows for iterating
42 /// through the set of contained files.
43 /// \see G::Path, G::FileSystem, G::File
44 ///
45 class G::Directory
46 {
47 public:
48 Directory() ;
49 ///< Default constructor for the current directory.
50
51 explicit Directory( const char * path ) ;
52 ///< Constructor.
53
54 explicit Directory( const Path & path ) ;
55 ///< Constructor.
56
57 explicit Directory( const std::string & path ) ;
58 ///< Constructor.
59
60 ~Directory() ;
61 ///< Destructor.
62
63 bool valid( bool for_creating_files = false ) const ;
64 ///< Returns true if the object represents a valid directory.
65 ///<
66 ///< Does additional checks if the 'for-creating-files'
67 ///< parameter is true. But note that the answer is not
68 ///< definitive -- file creation may fail, even if
69 ///< valid() returns true. For a more accurate test use
70 ///< writeable().
71
72 bool writeable( std::string probe_filename = tmp() ) const ;
73 ///< Tries to create and then delete an empty test file
74 ///< in the directory. Returns true on success.
75 ///< Precondition: valid()
76
77 Path path() const ;
78 ///< Returns the directory's path.
79
80 Directory( const Directory & other ) ;
81 ///< Copy constructor.
82
83 Directory & operator=( const Directory & ) ;
84 ///< Assignment operator.
85
86 static std::string tmp() ;
87 ///< A convenience function for constructing a filename for
88 ///< writeable(). This is factored-out to this public
89 ///< interface so that client code can minimise the time
90 ///< spent with a privileged effective userid.
91
92 private:
93 Path m_path ;
94 } ;
95
96 /// \class G::DirectoryIterator
97 /// A Directory iterator. The iteration model is
98 /// \code
99 /// while(iter.more()) { (void)iter.filePath() ; }
100 /// \endcode
101 ///
102 class G::DirectoryIterator
103 {
104 public:
105 explicit DirectoryIterator( const Directory & dir ) ;
106 ///< Constructor taking a directory reference.
107 ///< Iterates over all files in the directory.
108
109 ~DirectoryIterator() ;
110 ///< Destructor.
111
112 bool error() const ;
113 ///< Returns true on error. The caller should stop the iteration.
114
115 bool more() ;
116 ///< Returns true if more and advances by one.
117
118 bool isDir() const ;
119 ///< Returns true if the current item is a directory.
120
121 std::string sizeString() const ;
122 ///< Returns the file size as a decimal string. The value
123 ///< may be more than 32 bits. See also class G::Number.
124
125 Path filePath() const ;
126 ///< Returns the path of the current item.
127
128 std::string fileName() const ;
129 ///< Returns the name of the current item.
130
131 private:
132 DirectoryIterator( const DirectoryIterator & ) ; // not implemented
133 void operator=( const DirectoryIterator & ) ; // not implemented
134
135 private:
136 DirectoryIteratorImp * m_imp ;
137 } ;
138
139 /// \class G::DirectoryList
140 /// A Directory iterator with the same kind of interface as G::DirectoryIterator,
141 /// but doing all file i/o in one go. This is useful, compared to
142 /// DirectoryIterator, when temporarily adopting additional process privileges
143 /// to read a directory.
144 ///
145 class G::DirectoryList
146 {
147 public:
148 struct Item /// A directory-entry item for G::DirectoryList.
149 {
150 bool m_is_dir ;
151 Path m_path ;
152 std::string m_name ;
153 } ;
154
155 DirectoryList() ;
156 ///< Default constructor for an empty list. Initialise with one
157 ///< of the two read methods to do all the file i/o in one go.
158
159 void readAll( const Path & dir ) ;
160 ///< An initialiser that is to be used after default
161 ///< construction. Reads all files in the directory.
162
163 void readType( const Path & dir , const std::string & suffix , unsigned int limit = 0U ) ;
164 ///< An initialiser that is to be used after default
165 ///< construction. Reads all files that have the given
166 ///< suffix.
167
168 bool more() ;
169 ///< Returns true if more and advances by one.
170
171 bool isDir() const ;
172 ///< Returns true if the current item is a directory.
173
174 Path filePath() const ;
175 ///< Returns the current path.
176
177 std::string fileName() const ;
178 ///< Returns the current filename.
179
180 void sort() ;
181 ///< Sorts the files lexicographically.
182
183 static void readAll( const Path & dir , std::vector<Item> & out , bool sorted ) ;
184 ///< A static overload returning by reference a collection
185 ///< of Items.
186
187 private:
188 static bool compare( const Item & , const Item & ) ;
189
190 private:
191 bool m_first ;
192 unsigned int m_index ;
193 std::vector<Item> m_list ;
194 } ;
195
196 #endif
G::DirectoryIterator::sizeString
std::string sizeString() const
Returns the file size as a decimal string.
Definition: gdirectory_unix.cpp:154
G::DirectoryList::Item
A directory-entry item for G::DirectoryList.
Definition: gdirectory.h:148
G::DirectoryList::more
bool more()
Returns true if more and advances by one.
Definition: gdirectory.cpp:117
G::DirectoryIterator::filePath
Path filePath() const
Returns the path of the current item.
Definition: gdirectory_unix.cpp:139
G::DirectoryList::filePath
Path filePath() const
Returns the current path.
Definition: gdirectory.cpp:138
G::DirectoryList::readAll
void readAll(const Path &dir)
An initialiser that is to be used after default construction.
Definition: gdirectory.cpp:88
G::DirectoryList::sort
void sort()
Sorts the files lexicographically.
Definition: gdirectory.cpp:153
G::Directory::path
Path path() const
Returns the directory's path.
Definition: gdirectory.cpp:67
G::Directory::valid
bool valid(bool for_creating_files=false) const
Returns true if the object represents a valid directory.
Definition: gdirectory_unix.cpp:69
G::Directory::Directory
Directory()
Default constructor for the current directory.
Definition: gdirectory.cpp:32
G::Directory::writeable
bool writeable(std::string probe_filename=tmp()) const
Tries to create and then delete an empty test file in the directory.
Definition: gdirectory_unix.cpp:106
G::DirectoryIterator::~DirectoryIterator
~DirectoryIterator()
Destructor.
Definition: gdirectory_unix.cpp:159
G::DirectoryList::readType
void readType(const Path &dir, const std::string &suffix, unsigned int limit=0U)
An initialiser that is to be used after default construction.
Definition: gdirectory.cpp:93
G::Directory
An encapsulation of a file system directory that allows for iterating through the set of contained fi...
Definition: gdirectory.h:45
G
Low-level classes.
Definition: garg.h:29
G::DirectoryList
A Directory iterator with the same kind of interface as G::DirectoryIterator, but doing all file i/o ...
Definition: gdirectory.h:145
G::Directory::tmp
static std::string tmp()
A convenience function for constructing a filename for writeable().
Definition: gdirectory_unix.cpp:99
G::DirectoryIterator::more
bool more()
Returns true if more and advances by one.
Definition: gdirectory_unix.cpp:134
gexception.h
G::DirectoryIterator::isDir
bool isDir() const
Returns true if the current item is a directory.
Definition: gdirectory_unix.cpp:149
gpath.h
G::DirectoryIterator
A Directory iterator.
Definition: gdirectory.h:102
G::Directory::~Directory
~Directory()
Destructor.
Definition: gdirectory.cpp:52
G::DirectoryIteratorImp
A pimple-pattern implementation class for DirectoryIterator using opendir()/readdir().
Definition: gdirectory_unix.cpp:44
G::DirectoryIterator::fileName
std::string fileName() const
Returns the name of the current item.
Definition: gdirectory_unix.cpp:144
G::DirectoryList::isDir
bool isDir() const
Returns true if the current item is a directory.
Definition: gdirectory.cpp:133
G::Directory::operator=
Directory & operator=(const Directory &)
Assignment operator.
Definition: gdirectory.cpp:61
G::DirectoryIterator::error
bool error() const
Returns true on error. The caller should stop the iteration.
Definition: gdirectory_unix.cpp:129
G::DirectoryList::fileName
std::string fileName() const
Returns the current filename.
Definition: gdirectory.cpp:143
G::Path
A Path object represents a file system path.
Definition: gpath.h:72
G::DirectoryIterator::DirectoryIterator
DirectoryIterator(const Directory &dir)
Constructor taking a directory reference.
Definition: gdirectory_unix.cpp:124
G::DirectoryList::DirectoryList
DirectoryList()
Default constructor for an empty list.
Definition: gdirectory.cpp:74