source/modules/water/files/DirectoryIterator.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the Water library.
   5    Copyright (c) 2016 ROLI Ltd.
   6    Copyright (C) 2017-2024 Filipe Coelho <falktx@falktx.com>
   7
   8    Permission is granted to use this software under the terms of the ISC license
   9    http://www.isc.org/downloads/software-support-policy/isc-license/
  10
  11    Permission to use, copy, modify, and/or distribute this software for any
  12    purpose with or without fee is hereby granted, provided that the above
  13    copyright notice and this permission notice appear in all copies.
  14
  15    THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
  16    TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  17    FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
  18    OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  19    USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  20    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  21    OF THIS SOFTWARE.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef WATER_DIRECTORYITERATOR_H_INCLUDED
  27 #define WATER_DIRECTORYITERATOR_H_INCLUDED
  28
  29 #include "File.h"
  30 #include "../text/StringArray.h"
  31
  32 #include "CarlaScopeUtils.hpp"
  33
  34 namespace water {
  35
  36 //==============================================================================
  37 /**
  38     Searches through the files in a directory, returning each file that is found.
  39
  40     A DirectoryIterator will search through a directory and its subdirectories using
  41     a wildcard filepattern match.
  42
  43     If you may be scanning a large number of files, it's usually smarter to use this
  44     class than File::findChildFiles() because it allows you to stop at any time, rather
  45     than having to wait for the entire scan to finish before getting the results.
  46
  47     It also provides an estimate of its progress, using a (highly inaccurate!) algorithm.
  48 */
  49 class DirectoryIterator
  50 {
  51 public:
  52     //==============================================================================
  53     /** Creates a DirectoryIterator for a given directory.
  54
  55         After creating one of these, call its next() method to get the
  56         first file - e.g. @code
  57
  58         DirectoryIterator iter (File ("/animals/mooses"), true, "*.moose");
  59
  60         while (iter.next())
  61         {
  62             File theFileItFound (iter.getFile());
  63
  64             ... etc
  65         }
  66         @endcode
  67
  68         @param directory    the directory to search in
  69         @param isRecursive  whether all the subdirectories should also be searched
  70         @param wildCard     the file pattern to match. This may contain multiple patterns
  71                             separated by a semi-colon or comma, e.g. "*.jpg;*.png"
  72         @param whatToLookFor    a value from the File::TypesOfFileToFind enum, specifying
  73                                 whether to look for files, directories, or both.
  74     */
  75     DirectoryIterator (const File& directory,
  76                        bool isRecursive,
  77                        const String& wildCard = "*",
  78                        int whatToLookFor = File::findFiles);
  79
  80     /** Destructor. */
  81     ~DirectoryIterator();
  82
  83     /** Moves the iterator along to the next file.
  84
  85         @returns    true if a file was found (you can then use getFile() to see what it was) - or
  86                     false if there are no more matching files.
  87     */
  88     bool next();
  89
  90     /** Moves the iterator along to the next file, and returns various properties of that file.
  91
  92         If you need to find out details about the file, it's more efficient to call this method than
  93         to call the normal next() method and then find out the details afterwards.
  94
  95         All the parameters are optional, so pass null pointers for any items that you're not
  96         interested in.
  97
  98         @returns    true if a file was found (you can then use getFile() to see what it was) - or
  99                     false if there are no more matching files. If it returns false, then none of the
 100                     parameters will be filled-in.
 101     */
 102     bool next (bool* isDirectory,
 103                int64* fileSize,
 104                bool* isReadOnly);
 105
 106     /** Returns the file that the iterator is currently pointing at.
 107
 108         The result of this call is only valid after a call to next() has returned true.
 109     */
 110     const File& getFile() const;
 111
 112 private:
 113     //==============================================================================
 114     class NativeIterator
 115     {
 116     public:
 117         NativeIterator (const File& directory, const String& wildCard);
 118         ~NativeIterator();
 119
 120         bool next (String& filenameFound, bool* isDirectory, int64* fileSize, bool* isReadOnly);
 121
 122         class Pimpl;
 123
 124     private:
 125         friend class DirectoryIterator;
 126         CarlaScopedPointer<Pimpl> pimpl;
 127
 128         CARLA_DECLARE_NON_COPYABLE (NativeIterator)
 129     };
 130
 131     StringArray wildCards;
 132     NativeIterator fileFinder;
 133     String wildCard, path;
 134     int index;
 135     mutable int totalNumFiles;
 136     const int whatToLookFor;
 137     const bool isRecursive;
 138     bool hasBeenAdvanced;
 139     CarlaScopedPointer<DirectoryIterator> subIterator;
 140     File currentFile;
 141
 142     static StringArray parseWildcards (const String& pattern);
 143     static bool fileMatches (const StringArray& wildCards, const String& filename);
 144
 145     CARLA_DECLARE_NON_COPYABLE (DirectoryIterator)
 146 };
 147
 148 }
 149
 150 #endif // WATER_DIRECTORYITERATOR_H_INCLUDED