diff --git a/libs/openFrameworks/utils/ofFileUtils.cpp b/libs/openFrameworks/utils/ofFileUtils.cpp index 3877f7f4b71..e6dc7299cd8 100644 --- a/libs/openFrameworks/utils/ofFileUtils.cpp +++ b/libs/openFrameworks/utils/ofFileUtils.cpp @@ -467,12 +467,17 @@ void ofFile::close(){ //------------------------------------------------------------------------------------------------------------ bool ofFile::create(){ + return create(path()); +} + +//------------------------------------------------------------------------------------------------------------ +bool ofFile::create(const std::filesystem::path & path){ bool success = false; if(!myFile.string().empty()){ auto oldmode = this->mode; - auto oldpath = path(); - success = open(path(),ofFile::WriteOnly,binary); + auto oldpath = this->path(); + success = open(path,ofFile::WriteOnly,binary); close(); open(oldpath,oldmode,binary); } @@ -648,30 +653,46 @@ bool ofFile::isHidden() const { //------------------------------------------------------------------------------------------------------------ void ofFile::setWriteable(bool flag){ - setReadOnly(!flag); + try{ + if(flag){ + std::filesystem::permissions(myFile,std::filesystem::perms::owner_write | std::filesystem::perms::add_perms); + }else{ + std::filesystem::permissions(myFile,std::filesystem::perms::owner_write | std::filesystem::perms::remove_perms); + } + }catch(std::exception & e){ + ofLogError() << "Couldn't set write permission on " << myFile << ": " << e.what(); + } } //------------------------------------------------------------------------------------------------------------ +// deprecated void ofFile::setReadOnly(bool flag){ + setWriteable(!flag); +} + +//------------------------------------------------------------------------------------------------------------ +void ofFile::setReadable(bool flag){ try{ if(flag){ - std::filesystem::permissions(myFile,std::filesystem::perms::owner_write | std::filesystem::perms::remove_perms); - std::filesystem::permissions(myFile,std::filesystem::perms::owner_write | std::filesystem::perms::remove_perms); - std::filesystem::permissions(myFile,std::filesystem::perms::owner_write | std::filesystem::perms::remove_perms); + std::filesystem::permissions(myFile,std::filesystem::perms::owner_read | std::filesystem::perms::add_perms); }else{ - std::filesystem::permissions(myFile,std::filesystem::perms::owner_write | std::filesystem::perms::add_perms); + std::filesystem::permissions(myFile,std::filesystem::perms::owner_read | std::filesystem::perms::remove_perms); } }catch(std::exception & e){ - ofLogError() << "Couldn't set write permission on " << myFile << ": " << e.what(); + ofLogError() << "Couldn't set read permission on " << myFile << ": " << e.what(); } } //------------------------------------------------------------------------------------------------------------ void ofFile::setExecutable(bool flag){ try{ - std::filesystem::permissions(myFile, std::filesystem::perms::owner_exe | std::filesystem::perms::add_perms); + if(flag){ + std::filesystem::permissions(myFile, std::filesystem::perms::owner_exe | std::filesystem::perms::add_perms); + } else{ + std::filesystem::permissions(myFile, std::filesystem::perms::owner_exe | std::filesystem::perms::remove_perms); + } }catch(std::exception & e){ - ofLogError() << "Couldn't set write permission on " << myFile << ": " << e.what(); + ofLogError() << "Couldn't set executable permission on " << myFile << ": " << e.what(); } } @@ -899,7 +920,7 @@ ofDirectory::ofDirectory(const std::filesystem::path & path){ void ofDirectory::open(const std::filesystem::path & path){ originalDirectory = ofFilePath::getPathForDirectory(path.string()); files.clear(); - myDir = std::filesystem::path(ofToDataPath(originalDirectory)); + myDir = std::filesystem::path(ofToDataPath(originalDirectory)); } //------------------------------------------------------------------------------------------------------------ @@ -913,9 +934,9 @@ bool ofDirectory::create(bool recursive){ if(!myDir.string().empty()){ try{ if(recursive){ - std::filesystem::create_directories(myDir); + std::filesystem::create_directories(myDir); }else{ - std::filesystem::create_directory(myDir); + std::filesystem::create_directory(myDir); } } catch(std::exception & except){ @@ -972,8 +993,14 @@ void ofDirectory::setWriteable(bool flag){ } //------------------------------------------------------------------------------------------------------------ +// deprecated void ofDirectory::setReadOnly(bool flag){ - return ofFile(myDir,ofFile::Reference).setReadOnly(flag); + setWriteable(!flag); +} + +//------------------------------------------------------------------------------------------------------------ +void ofDirectory::setReadable(bool flag){ + return ofFile(myDir,ofFile::Reference).setReadable(flag); } //------------------------------------------------------------------------------------------------------------ @@ -1062,9 +1089,9 @@ bool ofDirectory::remove(bool recursive){ try{ if(recursive){ - std::filesystem::remove_all(std::filesystem::canonical(myDir)); + std::filesystem::remove_all(std::filesystem::canonical(myDir)); }else{ - std::filesystem::remove(std::filesystem::canonical(myDir)); + std::filesystem::remove(std::filesystem::canonical(myDir)); } }catch(std::exception & except){ ofLogError("ofDirectory") << "remove(): unable to remove file/directory: " << except.what(); @@ -1190,18 +1217,18 @@ static bool natural(const ofFile& a, const ofFile& b) { //------------------------------------------------------------------------------------------------------------ void ofDirectory::sort(){ - if(files.empty() && !myDir.empty()){ - listDir(); - } + if(files.empty() && !myDir.empty()){ + listDir(); + } ofSort(files, natural); } //------------------------------------------------------------------------------------------------------------ ofDirectory ofDirectory::getSorted(){ - ofDirectory sorted(*this); - sorted.listDir(); - sorted.sort(); - return sorted; + ofDirectory sorted(*this); + sorted.listDir(); + sorted.sort(); + return sorted; } //------------------------------------------------------------------------------------------------------------ @@ -1521,24 +1548,24 @@ string ofFilePath::getUserHomeDir(){ } string ofFilePath::makeRelative(const std::string & from, const std::string & to){ - auto pathFrom = std::filesystem::absolute( from ); - auto pathTo = std::filesystem::absolute( to ); - std::filesystem::path ret; - std::filesystem::path::const_iterator itrFrom( pathFrom.begin() ), itrTo( pathTo.begin() ); - // Find common base - for( std::filesystem::path::const_iterator toEnd( pathTo.end() ), fromEnd( pathFrom.end() ) ; itrFrom != fromEnd && itrTo != toEnd && *itrFrom == *itrTo; ++itrFrom, ++itrTo ); - // Navigate backwards in directory to reach previously found base - for( std::filesystem::path::const_iterator fromEnd( pathFrom.end() ); itrFrom != fromEnd; ++itrFrom ){ - if( (*itrFrom) != "." ){ - ret /= ".."; - } - } - // Now navigate down the directory branch - for( ; itrTo != pathTo.end() ; ++itrTo ){ - if( itrTo->string() != "."){ - ret /= *itrTo; - } - } - - return ret.string(); + auto pathFrom = std::filesystem::absolute( from ); + auto pathTo = std::filesystem::absolute( to ); + std::filesystem::path ret; + std::filesystem::path::const_iterator itrFrom( pathFrom.begin() ), itrTo( pathTo.begin() ); + // Find common base + for( std::filesystem::path::const_iterator toEnd( pathTo.end() ), fromEnd( pathFrom.end() ) ; itrFrom != fromEnd && itrTo != toEnd && *itrFrom == *itrTo; ++itrFrom, ++itrTo ); + // Navigate backwards in directory to reach previously found base + for( std::filesystem::path::const_iterator fromEnd( pathFrom.end() ); itrFrom != fromEnd; ++itrFrom ){ + if( (*itrFrom) != "." ){ + ret /= ".."; + } + } + // Now navigate down the directory branch + for( ; itrTo != pathTo.end() ; ++itrTo ){ + if( itrTo->string() != "."){ + ret /= *itrTo; + } + } + + return ret.string(); } diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index 35e30ea3ce8..13244db33c0 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -15,93 +15,126 @@ namespace std { //---------------------------------------------------------- /// \class ofBuffer -/// \brief a buffer of raw byte data which can be accessed as simple bytes or as text +/// +/// \brief A buffer of data which can be accessed as simple bytes or text. +/// class ofBuffer{ public: ofBuffer(); - /// \brief create a buffer and set it's contents from a raw byte pointer + /// \brief Create a buffer and set its contents from a raw byte pointer. + /// /// \param buffer pointer to the raw byte buffer to copy data from /// \param _size the number of bytes to read /// \warning buffer *must* not be NULL /// \warning _size *must* be <= the number of bytes allocated in _buffer ofBuffer(const char * buffer, std::size_t size); - /// \brief create a buffer and set it's contents from a string + /// \brief Create a buffer and set its contents from a string. + /// /// \param text string to copy data from ofBuffer(const string & text); - /// \brief create a buffer and set it's contents from an input stream + /// \brief Create a buffer and set its contents from an input stream. + /// /// \param ioBlockSize the number of bytes to read from the stream in chunks ofBuffer(istream & stream, size_t ioBlockSize = 1024); - /// \brief set contents of the buffer from a raw byte pointer - /// \param buffer pointer to the raw byte buffer to copy data from - /// \param _size the number of bytes to read + /// \brief Set the contents of the buffer from a raw byte pointer. + /// /// \warning buffer *must* not be NULL /// \warning _size *must* be <= the number of bytes allocated in _buffer + /// \param buffer pointer to the raw byte buffer to copy data from + /// \param _size the number of bytes to read void set(const char * _buffer, std::size_t _size); - /// \brief set contents of the buffer from a string + /// \brief Set contents of the buffer from a string. + /// /// \param text string to copy data from void set(const string & text); - /// \brief set contents of the buffer from an input stream + /// \brief Set contents of the buffer from an input stream. + /// /// \param stream input stream to copy data from /// \param ioBlockSize the number of bytes to read from the stream in chunks bool set(istream & stream, size_t ioBlockSize = 1024); - /// \brief set all bytes in the buffer to a given value + /// \brief Set all bytes in the buffer to a given value. + /// /// \param mem byte value to set void setall(char mem); - /// \brief append bytes to the end of buffer from a string + /// \brief Append bytes to the end of buffer from a string. + /// /// \param _buffer string to copy bytes from void append(const string& _buffer); - /// \brief append bytes to the end of the buffer from a raw byte pointer - /// \param buffer pointer to the raw byte buffer to copy data from - /// \param _size the number of bytes to read + /// \brief Append bytes to the end of the buffer from a raw byte pointer. + /// /// \warning buffer *must* not be NULL /// \warning _size *must* be <= the number of bytes allocated in _buffer + /// \param buffer pointer to the raw byte buffer to copy data from + /// \param _size the number of bytes to read void append(const char * _buffer, std::size_t _size); - /// \brief request that the buffer capacity be at least enough to contain a specified number of bytes + /// \brief Request that the buffer capacity be at least enough to contain a + /// specified number of bytes. + /// /// \param size number of bytes to reserve space for void reserve(size_t size); - /// \brief write contents of the buffer to an output stream + /// \brief Write contents of the buffer to an output stream. bool writeTo(ostream & stream) const; - /// \brief removes all bytes from the buffer leaving a size of 0 + /// \brief Remove all bytes from the buffer, leaving a size of 0. void clear(); - /// \brief request that the buffer capacity be at least enough to contain a specified number of bytes + /// \brief Request that the buffer capacity be at least enough to contain a + /// specified number of bytes. + /// /// \param _size number of bytes to reserve space for void allocate(std::size_t _size); - /// \brief resize the buffer so that it contains a specified number of bytes + /// \brief Resize the buffer to contain a specified number of bytes. + /// + /// If _size is < the current buffer size, the contents are reduced to _size + /// bytes & remaining bytes are removed. If _size is > the current buffer + /// size, the buffer's size is increased to _size_ bytes. + /// /// \param _size number of bytes to resize the buffer to - /// if _size is < the current buffer size, the contents are reduced to _size bytes & remaining bytes are removed - /// if _size is > the current buffer size, the buffer's size is increased to _size_ bytes - void resize(std::size_t _size); + void resize(std::size_t _size); - /// \return pointer to internal raw bytes - /// \warning do not access bytes at indices beyond size()! + /// \brief Access the buffer's contents using a raw byte pointer. + /// + /// \warning Do not access bytes at indices beyond size()! + /// \returns pointer to internal raw bytes char * getData(); - /// \return const pointer to internal raw bytes - /// \warning do not access bytes at indices beyond size()! + /// \brief Access the buffer's contents using a const raw byte pointer. + /// + /// \warning Do not access bytes at indices beyond size()! + /// \returns const pointer to internal raw bytes const char * getData() const; OF_DEPRECATED_MSG("Use getData instead",char * getBinaryBuffer()); OF_DEPRECATED_MSG("Use getData instead",const char * getBinaryBuffer() const); - string getText() const; //< /brief get the contents of the buffer as a string - operator string() const; //< /brief allows use a buffer as a string via cast - ofBuffer & operator=(const string & text); //< /brief set contents of the buffer from a string + /// \brief Get the contents of the buffer as a string. + /// + /// \returns buffer contents as a string + string getText() const; + + /// \brief Use buffer as a string via cast. + /// + /// \returns buffer contents as a string + operator string() const; + + /// \brief set contents of the buffer from a string + ofBuffer & operator=(const string & text); - /// \return the size of the buffer's content in bytes + /// \brief Check the buffer's size. + /// + /// \returns the size of the buffer's content in bytes std::size_t size() const; OF_DEPRECATED_MSG("use a lines iterator instead",string getNextLine()); @@ -122,37 +155,55 @@ class ofBuffer{ vector::const_reverse_iterator rend() const; /// \class Line - /// \brief a line of text in the buffer + /// + /// \brief A line of text in the buffer. + /// struct Line: public std::iterator{ Line(vector::iterator _begin, vector::iterator _end); - const string & operator*() const; - const string * operator->() const; - const string & asString() const; - Line& operator++(); //< increment to the next line - Line operator++(int); //< increment to a number of lines - bool operator!=(Line const& rhs) const; - bool operator==(Line const& rhs) const; - bool empty() const; //< is this line empty? (aka empty string "") + const string & operator*() const; + const string * operator->() const; + const string & asString() const; + + /// \brief Increment to the next line. + Line& operator++(); + + /// \brief Increment to a number of lines. + Line operator++(int); + + bool operator!=(Line const& rhs) const; + bool operator==(Line const& rhs) const; + + /// \brief Is this line empty? (aka an empty string "") + bool empty() const; private: - string line; - vector::iterator _current, _begin, _end; + string line; + vector::iterator _current, _begin, _end; }; /// \class Lines - /// \brief a series of text lines in the buffer + /// + /// \brief A series of text lines in the buffer. + /// struct Lines{ Lines(vector::iterator begin, vector::iterator end); - Line begin(); //< \brief get the first line in the buffer - Line end(); //< \brief get the last line in the buffer + + /// \brief Get the first line in the buffer. + Line begin(); + + /// \brief Get the last line in the buffer. + Line end(); private: - vector::iterator _begin, _end; + vector::iterator _begin, _end; }; - /// \return the contents of the buffer as a series of text lines - /// ie. if the buffer loads a text file with lines separated by an endline - /// char '\n', you can access each line individually using Line structs + /// \brief Access the contents of the buffer as a series of text lines. + /// + /// If the buffer loads a text file with lines separated by an endline + /// char '\n', you can access each line individually using Line structs. + /// + /// \returns buffer text lines Lines getLines(); private: @@ -161,126 +212,194 @@ class ofBuffer{ }; //-------------------------------------------------- -/// \brief read the contents of a file at path into a buffer -/// opens as a text file by default +/// \brief Read the contents of a file at path into a buffer. +/// +/// Opens as a text file by default. +/// /// \param path file to open -/// \param binary set to true if you are reading binary data aka an image, not text -ofBuffer ofBufferFromFile(const string & path, bool binary=false); +/// \param binary set to false if you are reading a text file & want lines +/// split at endline characters automatically +ofBuffer ofBufferFromFile(const string & path, bool binary=true); //-------------------------------------------------- -/// \brief write the contents of a buffer to a file at path -/// saves as a text file by default -/// \param binary set to true if you are writing binary data aka an image, not text -bool ofBufferToFile(const string & path, ofBuffer & buffer, bool binary=false); +/// \brief Write the contents of a buffer to a file at path. +/// +/// Saves as a text file by default. +/// +/// \param path file to open +/// \param buffer data source to write from +/// \param binary set to false if you are writing a text file & want lines +/// split at endline characters automatically +bool ofBufferToFile(const string & path, ofBuffer & buffer, bool binary=true); //-------------------------------------------------- /// \class ofFilePath -/// \brief static class for working with file path strings +/// +/// \brief Static class for working with file path strings. +/// class ofFilePath{ public: - /// \return the extension of a filename, ie. "duck.jpg" -> "jpg" + /// \brief Get the extension of a filename, ie. "duck.jpg" -> "jpg". + /// /// \param filename file path + /// \returns filename extension only static string getFileExt(const std::string& filename); - /// \return the filename without it's extension, ie. "duck.jpg" ->"duck" + /// \brief Remove extension from a filename, ie. "duck.jpg" ->"duck". + /// /// \param filename file path + /// \returns filename without extension static string removeExt(const std::string& filename); - /// \return a path prepended with a slash, ie. "images" -> "/images" + /// \brief Prepend path with a slash, ie. "images" -> "/images". + /// /// \param path file or directory path + /// \returns slah + path static string addLeadingSlash(const std::string& path); - /// \return a path appended with a slash, ie. "images" -> "images/" + /// \brief Append path with a slash, ie. "images" -> "images/". + /// /// \param path directory path + /// \returns path + slash static string addTrailingSlash(const std::string& path); - /// \return a path with the trailing slash removed (if found), ie. "images/" -> "images" + /// \brief Remove a path's trailing slash (if found), + /// ie. "images/" -> "images". + /// /// \param path directory path + /// \returns path minus trailing slash static string removeTrailingSlash(const std::string& path); - /// \return a cleaned up a directory path by adding a trailing slash if needed + /// \brief Cleaned up a directory path by adding a trailing slash if needed. + /// + /// For Windows-style path strings using "\", a "\" will be added. + /// For Unix-style path strings using "/", a "/" will be added. + /// /// \param path directory path - /// if it's a windows-style path string using "\", it will add a "\" - /// if it's a unix-style path string using "/", it will add a "/" + /// \returns cleaned path + trailing slash (if needed) static string getPathForDirectory(const std::string& path); - /// \return the absolute, full path for a given path - /// ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images" + /// \brief Get the absolute, full path for a given path, + /// ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images". + /// /// \param path file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* - /// in the data folder and want the direct path without relative ../../ + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder and want the direct path without relative + /// "../../" + /// \returns absolute path static string getAbsolutePath(const std::string& path, bool bRelativeToData = true); - /// \return true if the path is an absolute path + /// \brief Check if a path is an absolute (aka a full path), + /// ie. "images" -> false, + /// "/Users/mickey/of/apps/myApps/Donald/bin/data/images" -> true. + /// /// \param path file or directory path - /// ie. "images" -> false, "/Users/mickey/of/apps/myApps/Donald/bin/data/images" -> true + /// \returns true if the path is an absolute path static bool isAbsolute(const std::string& path); - /// \return the filename of a given path by stripping the parent directories - /// ie. "images/duck.jpg" -> "duck.jpg", assumes the path is in the data folder + /// \brief Get the filename of a given path by stripping the parent + /// directories ie. "images/duck.jpg" -> "duck.jpg", assumes the path is in + /// the data folder. + /// /// \param filePath file path - /// \param bRelativeToData set to false if you are working with paths that are *not* - /// in the data folder and want the direct path without relative ../../ + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder and want the direct path without relative + /// "../../" + /// \returns filename static string getFileName(const std::string& filePath, bool bRelativeToData = true); - /// \return a file path without it's last component - /// ie. "images/duck.jpg" -> "images" and "images/some/folder" -> "images/some" + /// \brief Get a file path without its last component, + /// ie. "images/duck.jpg" -> "images" and + /// "images/some/folder" -> "images/some" + /// /// \param filePath file path + /// \returns basename static string getBaseName(const std::string& filePath); - /// \return the enclosing parent directory of a path - /// ie. "images/duck.jpg" -> "images", assumes the path is in the data folder + /// \brief Get the enclosing parent directory of a path, + /// ie. "images/duck.jpg" -> "images", assumes the path is in the data + /// directory. + /// /// \param filePath file path - /// \param bRelativeToData set to false if you are working with paths that are *not* - /// in the data folder and want the direct path without relative ../../ + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder and want the direct path without relative + /// "../../" + ///\returns enclosing directory static string getEnclosingDirectory(const std::string& filePath, bool bRelativeToData = true); - /// \brief create the enclosing parent directory of a path - /// ie. "images" is the enclosing dir of "duck.jpg" = "images/duck.jpg" - /// assumes the path is in the data folder & automatically creates nested dirs as required - /// \param bRecursive set = false to override automatically nest dir creation - /// \param bRelativeToData set to false if you are working with paths that are *not* - /// in the data folder and want the direct path without relative ../../ + /// \brief Create the enclosing parent directory of a path, ie. + /// "images" is the enclosing directory of "duck.jpg" = "images/duck.jpg". + /// + /// Assumes the path is in the data folder & automatically creates nested + /// directories as required. + /// + /// \param bRecursive set to false to override automatically nested + /// directory creation + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder and want the direct path without relative + /// "../../" + /// \returns true if the enclosing directory was created static bool createEnclosingDirectory(const std::string& filePath, bool bRelativeToData = true, bool bRecursive = true); - /// \return the full path to the app's current working directory - /// this may be the app's parent directory or the location the app was launched from (aka on the commandline) - /// \warning this location *may* change if you or a library calls the cd() std C function + /// \brief Get the full path to the app's current working directory. + /// + /// This may be the app's parent directory or the location the app was + /// launched from (aka on the commandline). + /// + /// \warning This location *may* change if you or a library calls the cd() + /// std C function. + /// \returns current working directory static string getCurrentWorkingDirectory(); - /// \return a single path by joining path1 & path2 using a slash - /// ie. "/hello/world" + "foo/bar" -> "/hello/world/foo/bar" + /// \brief Create a single path by joining path1 & path2 using a slash, + /// ie. "/hello/world" + "foo/bar" -> "/hello/world/foo/bar". + /// /// \param path1 left half of the path to join /// \param path2 right half of the path to join + /// \returns joined path static string join(const std::string& path1, const std::string& path2); - /// \return the full path to the application's executable file + /// \brief Get the full path to the application's executable file. + /// /// Mac: the binary within the application's .app bundle Contents/MacOS dir /// Windows: the .exe /// Linux: the binary file itself + /// + /// \returns current executable path static string getCurrentExePath(); - /// \returns the full path to the application's parent directory + /// \brief Get the full path to the application's parent directory. + /// /// Windows & Linux: the application's parent directory /// Mac: the Contents/MacOS folder within the application's .app bundle + /// + /// \returns current executable directory static string getCurrentExeDir(); - /// \returns absolute path to the user's home directory, + /// \brief Get the absolute path to the user's home directory. + /// /// Mac OSX: /Users/ /// Windows: \Users\ /// Linux: /home/ + /// + /// \returns home directory path static string getUserHomeDir(); - /// \returns one path relative to another - /// ie. the relative path of "images/felines/lions" to "images/felines/tigers" is "../tigers" + /// \brief Make one path relative to another, + /// ie. the relative path of "images/felines/lions" to + /// "images/felines/tigers" is "../tigers". + /// /// \param from starting path /// \param to destination path + /// \returns relative path static string makeRelative(const std::string & from, const std::string & to); }; /// \class ofFile +/// /// \brief path to a file or directory +/// /// inherits from an fstream so you can read/write using the stream operators /// once a file path has been opened class ofFile: public fstream{ @@ -296,145 +415,235 @@ class ofFile: public fstream{ Append //< append data to the end of the file, do not overwrite }; - /// \brief create an ofFile instance - /// does not refer to a specific file until you either open a file or create a file or directory path + /// \brief Create an ofFile instance. + /// + /// Does not refer to a specific file until you either open a file or create + /// a file or directory path. ofFile(); - /// \brief create a new ofFile instance and attempt to open the path as a file - /// opens as a binary file with read only access by default + /// \brief Create a new ofFile instance and attempt to open the path as a + /// file. + /// + /// Opens as a binary file with read only access by default. + /// /// \param path file path - /// \param mode file access mode depending on how you plan to use the file (read only, read write, etc) - /// \param binary set to false if you are explicitly creating a text file + /// \param mode file access mode depending on how you plan to use the file + /// (read only, read write, etc) + /// \param binary set to false if you are working with a text file & want + /// lines split at endline characters automatically ofFile(const std::filesystem::path & path, Mode mode=ReadOnly, bool binary=true); - /// \brief create a new file path using the same path & settings of another file + /// \brief Create a new file path using the same path & settings of another + /// file. + /// /// \param mom ofFile instance source ofFile(const ofFile & mom); - /// \brief copy the path and settings of an ofFile into this instance + /// \brief Copy the path and settings of an ofFile into this instance. + /// /// \param mom ofFile instance source ofFile & operator= (const ofFile & mom); ~ofFile(); - /// \brief open the path as a file - /// opens as a text file with read only access by default + /// \brief Open the path as a file. + /// + /// Opens as a text file with read only access by default. + /// /// \param path file path - /// \param mode file access mode depending on how you plan to use the file (read only, read write, etc) - /// \param binary set to true if you are working with binary data (aka image, not text) - bool open(const std::filesystem::path & path, Mode mode=ReadOnly, bool binary=false); - - /// \brief reopen the current file path with a different access mode (read only, read write, etc) - /// \param mode file access mode depending on how you plan to use the file (read only, read write, etc) - /// \param binary set to true if you are working with binary data (aka image, not text) - bool changeMode(Mode mode, bool binary=false); - - /// \brief close a currently open file + /// \param mode file access mode depending on how you plan to use the file + /// (read only, read write, etc) + /// \param binary set to false if you are reading a text file & want lines + /// split at endline characters automatically + /// \returns true if the path was opened + bool open(const std::filesystem::path & path, Mode mode=ReadOnly, bool binary=true); + + /// \brief Reopen the current file path with a different access mode. + /// + /// \param mode file access mode depending on how you plan to use the file + /// (read only, read write, etc) + /// \param binary set to false if you are reading a text file & want lines + /// split at endline characters automatically + /// \returns true if the file was reopened with the new access mode(s). + bool changeMode(Mode mode, bool binary=true); + + /// \brief Close a currently open file. void close(); - /// \brief create a file at the current path + /// \brief Create a file at the current path. + /// + /// Creates as a write only binary file by default. + /// + /// \returns true if the file was created bool create(); - /// \return true if a file exists at the current path + /// \brief Create a file at a given path. + /// + /// Creates as a write only binary file by default. + /// + /// \param path file path + /// \returns true if the file was created + bool create(const std::filesystem::path & path); + + /// \brief Check if a file exists at the current path. + /// + /// \returns true if the file exists bool exists() const; - /// \return the current path + /// \brief Get the current path. + /// + /// \returns current path string path() const; - /// \return the current path without it's extension, ie. "duck.jpg" ->"duck" + /// \brief Get the current path without its extension, + /// ie. "duck.jpg" ->"duck". + /// + /// \returns current path file extension string getExtension() const; - /// \return the filename of the current path by stripping the parent directories - /// ie. "images/duck.jpg" -> "duck.jpg" + /// \brief Get the filename of the current path by stripping the parent + /// directories, ie. "images/duck.jpg" -> "duck.jpg". + /// + /// \returns current path filename string getFileName() const; - /// \return the current path without it's last component - /// ie. "images/duck.jpg" -> "images" and "images/some/folder" -> "images/some" + /// \biref Get the current path without its last component, + /// ie. "images/duck.jpg" -> "images" and + /// "images/some/folder" -> "images/some". + /// + /// \returns current path basename string getBaseName() const; - /// \return the enclosing parent directory of a path - /// ie. "images/duck.jpg" -> "images", assumes the path is in the data folder + /// \brief Get the enclosing parent directory of a path, + /// ie. "images/duck.jpg" -> "images", assumes the path is in the data + /// directory. + /// + /// \returns current path's enclosing directory string getEnclosingDirectory() const; - /// \return the absolute, full path of the file - /// ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images" + /// \biref Get the absolute, full path of the file, + /// ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images". + /// + /// \returns current path as an absolute path string getAbsolutePath() const; - /// \return true if the current path is readable + /// \brief Check if the current path is readable. + /// + /// \returns true if readable bool canRead() const; - /// \return true if the current path is writable + /// \brief Check if the current path is writable. + /// + /// \returns true if writable bool canWrite() const; - /// \return true if the current path is executable + /// \brief Check if the current path is executable. + /// + /// \returns true if executable bool canExecute() const; - /// \return true if the current path is a file and not a directory + /// \brief Check if the current path is a file and not a directory. + /// + /// \returns true if a file bool isFile() const; - /// \return true if the current path is a system link to another file or directory + /// \brief Check if the current path is a system link to another file or + /// directory. + /// + /// \returns true if a system link bool isLink() const; - /// \return true if the current path is a directory and not a file + /// \brief Check if the current path is a directory and not a file. + /// + /// \returns true if a directory bool isDirectory() const; - /// \return true if the current path is a device file - /// works on Mac & Linux which can represent devices as files, - /// always returns false on Windows + /// \brief Check if the current path is a device file. + /// + /// Works on Mac & Linux which can represent devices as files, however + /// always returns false on Windows. + /// + /// \returns true if a device file bool isDevice() const; - /// \return true if the current path is hidden - /// works on Mac & Linux which denote hidden files by prepending a period - /// to the filename -> ".hello", always returns false on Windows + /// \brief Check if the current path is hidden. + /// + /// Works on Mac & Linux which denote hidden files by prepending a period + /// to the filename -> ".hello", however always returns false on Windows. + /// + /// \returns true if hidden bool isHidden() const; - /// \brief set the writable flag of the current path + /// \brief Set the writable flag of the current path. void setWriteable(bool writeable=true); + + OF_DEPRECATED_MSG("Use ofFile::setWriteable(!flag).", void setReadOnly(bool flag)); - /// \brief set the readable flag of the current path - void setReadOnly(bool readable=true); + /// \brief Set the readable flag of the current path. + void setReadable(bool readable=true); - /// \brief set the executable flag of the current path + /// \brief Set the executable flag of the current path. void setExecutable(bool executable=true); - /// \brief copy the current file or directory path to a new path - /// copies relative to the data path & does *not* overwrite by default - /// does not change the current path & assumes the new path is in the data folder + /// \brief Copy the current file or directory path to a new path. + /// + /// Copies relative to the data path & does *not* overwrite by default + /// does not change the current path & assumes the new path is in the data + /// folder. + /// /// \param path destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful bool copyTo(const std::string& path, bool bRelativeToData = true, bool overwrite = false) const; - /// \brief move the current file or directory path to a new path - /// moves relative to the data path & does *not* overwrite by default - /// does not change the current path & assumes the new path is in the data folder + /// \brief Move the current file or directory path to a new path. + /// + /// Moves relative to the data path & does *not* overwrite by default + /// does not change the current path & assumes the new path is in the data + /// folder. + /// /// \param path destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful bool moveTo(const std::string& path, bool bRelativeToData = true, bool overwrite = false); - /// \brief rename the current file or directory path to a new path - /// renames relative to the data path & does *not* overwrite by default - /// does not change the current path & assumes the new path is in the data folder + /// \brief Rename the current file or directory path to a new path. + /// + /// Renames relative to the data path & does *not* overwrite by default + /// does not change the current path & assumes the new path is in the data + /// folder. + /// /// \param path destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful bool renameTo(const std::string& path, bool bRelativeToData = true, bool overwrite = false); - /// \brief removes the file or directory at the current path - /// does not remove non-empty directories by default - /// \param recursive set to true to remove a non-empty directory and it's contents - /// \warning be careful! this deletes a file or folder :) - /// \return true if the path was removed successfully + /// \brief Removes the file or directory at the current path. + /// + /// Does not remove non-empty directories by default. + /// + /// \warning Be careful! This deletes a file or folder. :) + /// \param recursive set to true to remove a non-empty directory and its + /// contents + /// \returns true if the path was removed successfully bool remove(bool recursive=false); - /// \return the size of the file at the current file path + /// \brief get the size of the file at the current file path + /// + /// \returns size in bytes uint64_t getSize() const; - // this allows to compare files by their paths, also provides sorting and use as key in stl containers + // this allows to compare files by their paths, also provides sorting + // and use as key in stl containers bool operator==(const ofFile & file) const; bool operator!=(const ofFile & file) const; bool operator<(const ofFile & file) const; @@ -449,59 +658,83 @@ class ofFile: public fstream{ // since this class inherits from fstream it can be used as a r/w stream: // http://www.cplusplus.com/reference/iostream/fstream/ - /// read the contents of a file at the current path into a buffer + /// \brief Read the contents of a file at the current path into a buffer. + /// + /// \returns buffer with file contents ofBuffer readToBuffer(); - /// write the contents of a buffer into a file at the current path + /// \brief Write the contents of a buffer into a file at the current path. + /// + /// \param buffer source byte buffer + /// \returns true if buffer's contents written successfully bool writeFromBuffer(const ofBuffer & buffer); - /// read the entire contents of the currently opened file into an output stream, - /// basically an easy to use equivalent to rdbuf() + /// \brief Read the entire contents of the currently opened file into an + /// output stream. + /// + /// This is basically an easy to use equivalent to rdbuf(): /// ie. ofLogNotice() << file.getFileBuffer(); /// write_file << file.getFileBuffer(); + /// + /// \return output stream filebuf * getFileBuffer() const; operator std::filesystem::path(){ return myFile; } - operator const std::filesystem::path() const{ - return myFile; - } + operator const std::filesystem::path() const{ + return myFile; + } //------- //static helpers //------- - /// \brief copy source path to destination path - /// copies relative to the data path & does *not* overwrite by default - /// assumes the source & destination path is in the data folder + /// \brief Copy source path to destination path. + /// + /// Copies relative to the data path & does *not* overwrite by default + /// assumes the source & destination path is in the data directory. + /// /// \param pathSrc source file or directory path /// \param pathDst destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful static bool copyFromTo(const std::string& pathSrc, const std::string& pathDst, bool bRelativeToData = true, bool overwrite = false); - /// \brief move source path to destination path - /// moves relative to the data path & does *not* overwrite by default - /// assumes the source & destination path is in the data folder + /// \brief Move source path to destination path. + /// + /// Moves relative to the data path & does *not* overwrite by default + /// assumes the source & destination path is in the data directory. + /// /// \param pathSrc source file or directory path /// \param pathDst destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \warning be careful with slashes here, appending a slash when moving a folder may cause mad headaches in OSX - /// \return true if the move was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \warning be careful with slashes here, appending a slash when moving a + /// folder may cause mad headaches in OSX + /// \returns true if the move was successful static bool moveFromTo(const std::string& pathSrc, const std::string& pathDst, bool bRelativeToData = true, bool overwrite = false); - /// \brief check if a file or directory exists at a given path + /// \brief Check if a file or directory exists at a given path. + /// /// \param fPath file path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder and want the direct path without relative ../../ - /// \return true if a file or directory exists + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder and want the direct path without relative + /// "../../" + /// \returns true if a file or directory exists static bool doesFileExist(const std::string& fPath, bool bRelativeToData = true); - /// \brief remove a file or directory at a given path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder and want the direct path without relative ../../ + /// \brief Remove a file or directory at a given path. + /// + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder and want the direct path without relative + /// "../../" /// \returns true if the path was removed successfully static bool removeFile(const std::string& path, bool bRelativeToData = true); @@ -515,185 +748,285 @@ class ofFile: public fstream{ }; /// \class ofDirectory -/// \brief path to a directory, can be used to query file and directory contents +/// +/// \brief Path to a directory. Can be used to query file and directory +/// contents. +/// class ofDirectory{ public: - /// \brief create an ofDirectory instance - /// does not refer to a specific directory until you either open or create a directory path + /// \brief Create an ofDirectory instance + /// + /// Does not refer to a specific directory until you either open or create + /// a directory path. ofDirectory(); - /// \brief create an ofDirectory instance and attempt to open the path + /// \brief Create an ofDirectory instance and attempt to open the path. + /// /// \param path directory path ofDirectory(const std::filesystem::path & path); - /// \brief open a directory path - /// clears the current file list + /// \brief Open a directory path, clears the current file list. + /// /// \param path directory path void open(const std::filesystem::path & path); - /// \brief close the currently open path + /// \brief Close the currently open path. void close(); - /// \brief create a directory at the current path - /// \param bRecursive set to true to automatically create nested dirs as required + /// \brief Create a directory at the current path. + /// + /// \param bRecursive set to true to automatically create nested directories + /// as required bool create(bool recursive = false); - /// \return true if a directory exists at the current path + /// \brief Check if a directory exists at the current path. + /// + /// \returns true if exists bool exists() const; - /// \return the current path + /// \brief Get the current path. + /// + /// \returns current path string path() const; - /// \return the absolute, full path of the directory, - /// ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images" + /// \brief Get the absolute, full path of the directory, + /// ie. "images" -> "/Users/mickey/of/apps/myApps/Donald/bin/data/images". + /// + /// \return current path as an absolute path string getAbsolutePath() const; - /// \return true if the current path is readable + /// \brief Check if the current path is readable. + /// + /// \returns true if readable bool canRead() const; - /// \return true if the current path is writeable + /// \brief Check if the current path is writeable. + /// + /// \returns true if writable bool canWrite() const; - /// \return true if the current path is executable + /// \brief Check if the current path is executable. + /// + /// \returns true if executable bool canExecute() const; - /// \return true if the current path is indeed a directory and not a file + /// \brief Check if the current path is indeed a directory and not a file. + /// + /// \returns true if a directory bool isDirectory() const; - /// \return true if the current path is hidden - /// works on Mac & Linux which denote hidden directories by prepending - /// a period -> ".hello", always returns false on Windows + /// \brief Check if the current path is hidden. + /// + /// Works on Mac & Linux which denote hidden directories by prepending + /// a period -> ".hello", however always returns false on Windows. + /// + /// \returns true if hidden bool isHidden() const; - /// \brief set the writable flag of the current path + /// \brief Set the writable flag of the current path. + /// + /// \param writable set to true to make path writable void setWriteable(bool writeable=true); + + OF_DEPRECATED_MSG("Use ofDirectory::setWriteable(!flag).", void setReadOnly(bool flag)); - /// \brief set the readable flag of the current path - void setReadOnly(bool readable=true); + /// \brief Set the readable flag of the current path. + /// + /// \param readable set to true to make path readable + void setReadable(bool readable=true); - /// \brief set the executable flag of the current path + /// \brief Set the executable flag of the current path. + /// + /// \param executable set to true to make path executable void setExecutable(bool executable=true); - /// \brief show hidden files & directories when listing files? - /// Mac & Linux denote hidden directories by prepending a period -> ".hello" + /// \brief Show hidden files & directories when listing files? + /// + /// Mac & Linux denote hidden directories by prepending a period + /// -> ".hello". + /// + /// \param showHidden set to true to show hidden files void setShowHidden(bool showHidden); - /// \brief copy the current file or directory path to a new path - /// copies relative to the data path & does *not* overwrite by default - /// does not change the current path & assumes the new path is in the data folder + /// \brief Copy the current file or directory path to a new path. + /// + /// Copies relative to the data path & does *not* overwrite by default + /// does not change the current path & assumes the new path is in the data + /// directory. + /// /// \param path destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful bool copyTo(const string& path, bool bRelativeToData = true, bool overwrite = false); - /// \brief move the current file or directory path to a new path - /// moves relative to the data path & does *not* overwrite by default - /// does not change the current path & assumes the new path is in the data folder + /// \brief Move the current file or directory path to a new path. + /// + /// Moves relative to the data path & does *not* overwrite by default + /// does not change the current path & assumes the new path is in the data + /// directory. + /// /// \param path destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful bool moveTo(const string& path, bool bRelativeToData = true, bool overwrite = false); - /// \brief rename the current file or directory path to a new path - /// renames relative to the data path & does *not* overwrite by default - /// does not change the current path & assumes the new path is in the data folder + /// \brief Rename the current file or directory path to a new path. + /// + /// Renames relative to the data path & does *not* overwrite by default + /// does not change the current path & assumes the new path is in the data + /// directory. + /// /// \param path destination file or directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param overwrite set to true if you want to overwrite the file or directory at the new path - /// \return true if the copy was successful + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data folder + /// \param overwrite set to true if you want to overwrite the file or + /// directory at the new path + /// \returns true if the copy was successful bool renameTo(const string& path, bool bRelativeToData = true, bool overwrite = false); - /// \brief removes the file or directory at the current path - /// does not remove non-empty directories by default - /// \param recursive set to true to remove a non-empty directory and it's contents - /// \warning be careful! this deletes a file or folder :) - /// \return true if the path was removed successfully + /// \brief Removes the file or directory at the current path. + /// + /// Does not remove non-empty directories by default. + /// + /// \warning Be careful! This deletes a file or folder. :) + /// \param recursive set to true to remove a non-empty directory and its + /// contents + /// \returns true if the path was removed successfully bool remove(bool recursive); //------------------- // dirList operations //------------------- - /// \brief allow a file extension when listing the contents the current directory path - /// setting an allowed extension enables a whitelist mode which only lists extensions which have been - /// explicitly allowed + /// \brief Allow a file extension when listing the contents the current + /// directory path. + /// + /// Setting an allowed extension enables a whitelist mode which only lists + /// extensions which have been explicitly allowed. + /// /// \param extension file type extension ie. "jpg", "png", "txt", etc void allowExt(const string& extension); - /// \brief open and read the contents of a directory - /// uses allowed extension whitelist to ignore unwanted file types if allowExt() has been called + /// \brief Open and read the contents of a directory. + /// + /// Uses allowed extension whitelist to ignore unwanted file types if + /// allowExt() has been called. + /// /// \param path directory path - /// \return number of paths found + /// \returns number of paths found std::size_t listDir(const string& path); - /// \brief open and read the contents of the current directory - /// uses allowed extension whitelist to ignore unwanted file types if allowExt() has been called - /// \return number of paths found + /// \brief Open and read the contents of the current directory. + /// + /// Uses allowed extension whitelist to ignore unwanted file types if + /// allowExt() has been called. + /// + /// \returns number of paths found std::size_t listDir(); - /// \return the current path + /// \returns the current path string getOriginalDirectory() const; - /// \brief get the filename at a given position in the dir contents list ie. "duck.jpg" - /// \param position array index in the dir contents list - /// \warning call listDir() before using this function or the dir contents list will be empty - /// \throw throws an out of bounds exception if position >= the number of listed dir contents - /// \return file or directory name + /// \brief Get the filename at a given position in the directory contents + /// list, ie. "duck.jpg". + /// + /// \warning Call listDir() before using this function or the directory + /// contents list will be empty. + /// \throws Throws an out of bounds exception if position >= the number of + /// listed directory contents. + /// \param position array index in the directory contents list + /// \returns file or directory name string getName(std::size_t position) const; - /// \brief get the full path of the file or directory at a given position in the dir contents list - /// \param position array index in the dir contents list - /// \warning call listDir() before using this function or the dir contents list will be empty - /// \throw throws an out of bounds exception if position >= the number of listed dir contents - /// \return file or directory name including the current path + /// \brief Get the full path of the file or directory at a given position in + /// the directory contents list. + /// + /// \warning Call listDir() before using this function or the directory + /// contents list will be empty. + /// \throws Throws an out of bounds exception if position >= the number of + /// listed directory contents. + /// \param position array index in the directory contents list + /// \returns file or directory name including the current path string getPath(std::size_t position) const; - /// \brief open an ofFile instance using the path a given position in the dir contents list - /// opens as a text file with read only access by default - /// \param position array index in the dir contents list - /// \param mode file access mode depending on how you plan to use the file (read only, read write, etc) - /// \param binary set to true if you are working with binary data (aka image, not text) - /// \warning call listDir() before using this function or the dir contents list will be empty - /// \throw throws an out of bounds exception if position >= the number of listed dir contents - /// \return ofFile instance - ofFile getFile(std::size_t position, ofFile::Mode mode=ofFile::Reference, bool binary=false) const; - - /// \return files and directories in the dir contents list - /// directory contents are automatically listed + /// \brief Open an ofFile instance using the path a given position in the + /// directory contents list. + /// + /// Opens as a binary file with readonly access by default. + /// + /// \warning Call listDir() before using this function or the directory + /// contents list will be empty. + /// \throw Throws an out of bounds exception if position >= the number of + /// listed directory contents. + /// \param position array index in the directory contents list + /// \param mode file access mode depending on how you plan to use the file + /// (read only, read write, etc) + /// \param binary set to false if you are working with a text file & want + /// lines split at endline characters automatically + /// \returns ofFile instance + ofFile getFile(std::size_t position, ofFile::Mode mode=ofFile::Reference, bool binary=true) const; + + /// \brief Get files and directories in the directory contents list. + /// + /// Directory contents are automatically listed. + /// + /// \returns vector of files in the directory const vector & getFiles() const; - /// \brief dir contents array operator access - /// \param position array index in the dir contents list - /// \warning call listDir() before using this function or the dir contents list will be empty - /// \throw throws an out of bounds exception if position >= the number of listed dir contents - /// \return opened ofFile instance + /// \brief Access directory contents via th array operator. + /// + /// \warning Call listDir() before using this function or the directory + /// contents list will be empty. + /// \throw Throws an out of bounds exception if position >= the number of + /// listed directory contents. + /// \param position array index in the directory contents list + /// \returns opened ofFile instance ofFile operator[](std::size_t position) const; - /// \return true when hidden files & directories are included when listing files - /// Mac & Linux denote hidden directories by prepending a period -> ".hello" + /// \brief Check whether hidden files & directories are included when + /// listing files. + /// + /// Mac & Linux denote hidden directories by prepending a period + /// -> ".hello". + /// + /// \returns true if hidden files are shown bool getShowHidden() const; - /// \brief closes the directory, backwards compatibility with ofxDirList + /// \brief Closes the directory. + /// + /// This is for backwards compatibility with ofxDirList. void reset(); - /// \brief sort the dir contents list alphabetically - /// \warning call listDir() before using this function or their will be nothing to sort + /// \brief Sort the directory contents list alphabetically. + /// + /// \warning Call listDir() before using this function or there will be + /// nothing to sort. void sort(); - /// \return a sorted ofDirectory instance using the current path - ofDirectory getSorted(); + /// \brief Get a sorted ofDirectory instance using the current path. + /// + /// \returns sorted ofDirectory instance + ofDirectory getSorted(); - /// \return the number of paths in the current dir list - /// \warning call listDir() before using this function or it will return 0 + /// \brief Get the number of paths in the current directory list. + /// + /// \warning Call listDir() before using this function or it will return 0 + /// since the directory list will be empty. + /// \returns number of paths std::size_t size() const; OF_DEPRECATED_MSG("Use size() instead.", int numFiles()); - // this allows to compare dirs by their paths, also provides sorting and use as key in stl containers + // this allows to compare directories by their paths, also provides sorting + // and use as key in stl containers bool operator==(const ofDirectory & dir) const; bool operator!=(const ofDirectory & dir) const; bool operator<(const ofDirectory & dir) const; @@ -705,41 +1038,55 @@ class ofDirectory{ return myDir; } - operator const std::filesystem::path() const{ - return myDir; - } + operator const std::filesystem::path() const{ + return myDir; + } //------- // static helpers //------- - /// \brief create a directory at a given path - /// creates relative to the data path by default + /// \brief Create a directory at a given path. + /// + /// Creates relative to the data path by default. + /// /// \param dirPath directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \param bRecursive set to true to automatically create nested dirs as required - /// \return true if directory was created successfully + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \param bRecursive set to true to automatically create nested directories + /// as required + /// \returns true if directory was created successfully static bool createDirectory(const std::string& dirPath, bool bRelativeToData = true, bool recursive = false); - /// \brief check if a directory at a given path is empty - /// assumes directory path is relative to the data path by default + /// \brief Check if a directory at a given path is empty. + /// + /// Assumes directory path is relative to the data path by default. + /// /// \param dirPath directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \return true if the directory is empty aka contains no files or directories + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \returns true if the directory is empty aka contains no files or + /// directories static bool isDirectoryEmpty(const std::string& dirPath, bool bRelativeToData = true ); - /// \brief check if a directory exists at a given path - /// assumes directory path is relative to the data path by default + /// \brief Check if a directory exists at a given path. + /// + /// Assumes directory path is relative to the data path by default. + /// /// \param dirPath directory path - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \return true if the directory exists + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \returns true if the directory exists static bool doesDirectoryExist(const std::string& dirPath, bool bRelativeToData = true); /// \brief remove a directory at a given path - /// \param deleteIfNotEmpty set to true if you want to recursively delete the directory *and* it's contents - /// \param bRelativeToData set to false if you are working with paths that are *not* in the data folder - /// \return true if the path was removed successfully + /// + /// \param deleteIfNotEmpty set to true if you want to recursively delete + /// the directory *and* its contents + /// \param bRelativeToData set to false if you are working with paths that + /// are *not* in the data directory + /// \returns true if the path was removed successfully static bool removeDirectory(const std::string& path, bool deleteIfNotEmpty, bool bRelativeToData = true); vector::const_iterator begin() const; diff --git a/tests/utils/fileUtils/src/main.cpp b/tests/utils/fileUtils/src/main.cpp index 37206588830..0a93ef6e056 100644 --- a/tests/utils/fileUtils/src/main.cpp +++ b/tests/utils/fileUtils/src/main.cpp @@ -53,7 +53,7 @@ class ofApp: public ofxUnitTestsApp{ } ofFile("nowrite").create(); - ofFile("nowrite").setReadOnly(); + ofFile("nowrite").setWriteable(false); test(ofFile("nowrite").canRead(),"ofFile::canRead"); test(!ofFile("nowrite").canWrite(),"!ofFile::canWrite"); @@ -120,7 +120,7 @@ class ofApp: public ofxUnitTestsApp{ } ofDirectory("noreaddir").create(); - ofDirectory("noreaddir").setReadOnly(); + ofDirectory("noreaddir").setWriteable(false); test(ofDirectory("noreaddir").canRead(),"ofDirectory::canRead readonly"); test(!ofDirectory("noreaddir").canWrite(),"!ofDirectory::canWrite readonly");