/indra/llvfs/lldiriterator.h

 1/**
 2 * @file lldiriterator.h
 3 * @brief Iterator through directory entries matching the search pattern.
 4 *
 5 * $LicenseInfo:firstyear=2010&license=viewerlgpl$
 6 * Second Life Viewer Source Code
 7 * Copyright (C) 2010, Linden Research, Inc.
 8 *
 9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation;
12 * version 2.1 of the License only.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
22 *
23 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
24 * $/LicenseInfo$
25 */
26
27#ifndef LL_LLDIRITERATOR_H
28#define LL_LLDIRITERATOR_H
29
30#include "linden_common.h"
31
32/**
33 * Class LLDirIterator
34 *
35 * Iterates through directory entries matching the search pattern.
36 */
37class LLDirIterator
38{
39public:
40	/**
41	 * Constructs LLDirIterator object to search for glob pattern
42	 * matches in a directory.
43	 *
44	 * @param dirname - name of a directory to search in.
45	 * @param mask - search pattern, a glob expression
46	 *
47	 * Wildcards supported in glob expressions:
48	 * --------------------------------------------------------------
49	 * | Wildcard 	| Matches										|
50	 * --------------------------------------------------------------
51	 * | 	* 		|zero or more characters						|
52	 * | 	?		|exactly one character							|
53	 * | [abcde]	|exactly one character listed					|
54	 * | [a-e]		|exactly one character in the given range		|
55	 * | [!abcde]	|any character that is not listed				|
56	 * | [!a-e]		|any character that is not in the given range	|
57	 * | {abc,xyz}	|exactly one entire word in the options given	|
58	 * --------------------------------------------------------------
59	 */
60	LLDirIterator(const std::string &dirname, const std::string &mask);
61
62	~LLDirIterator();
63
64	/**
65	 * Searches for the next directory entry matching the glob mask
66	 * specified upon iterator construction.
67	 * Returns true if a match is found, sets fname
68	 * parameter to the name of the matched directory entry and
69	 * increments the iterator position.
70	 *
71	 * Typical usage:
72	 * <code>
73	 * LLDirIterator iter(directory, pattern);
74	 * if ( iter.next(scanResult) )
75	 * </code>
76	 *
77	 * @param fname - name of the matched directory entry.
78	 * @return true if a match is found, false otherwise.
79	 */
80	bool next(std::string &fname);
81
82protected:
83	class Impl;
84	Impl* mImpl;
85};
86
87#endif //LL_LLDIRITERATOR_H