From 64301c30072605d6fe5070fec5bb739fb61c7658 Mon Sep 17 00:00:00 2001 From: danomatika Date: Mon, 29 Feb 2016 17:53:28 -0700 Subject: [PATCH 1/7] edited doxy comments for ofFileUtils --- libs/openFrameworks/utils/ofFileUtils.h | 896 ++++++++++++++++-------- 1 file changed, 612 insertions(+), 284 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index 35e30ea3ce8..2dc0a88e643 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); - /// \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,17 +155,26 @@ 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 + + /// \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; - bool empty() const; //< is this line empty? (aka empty string "") + + /// \brief Is this line empty? (aka an empty string "") + bool empty() const; private: string line; @@ -140,19 +182,28 @@ class ofBuffer{ }; /// \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; }; - /// \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,192 @@ 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 +/// \param binary set to true if you are reading binary data ofBuffer ofBufferFromFile(const string & path, bool binary=false); //-------------------------------------------------- -/// \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 +/// \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 true if you are writing binary data bool ofBufferToFile(const string & path, ofBuffer & buffer, bool binary=false); //-------------------------------------------------- /// \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 +413,220 @@ 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 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 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) + /// \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) + /// \returns true if the path was opened 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) + /// \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 true if you are working with binary data + /// (aka image, not text) + /// \returns true if the file was reopened with the new access mode(s). bool changeMode(Mode mode, bool binary=false); - /// \brief close a currently open file + /// \brief Close a currently open file. void close(); - /// \brief create a file at the current path + /// \brief Create a file at the current path. bool create(); - /// \return true if a file exists at the current 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); - /// \brief set the readable flag of the current path + /// \brief Set the readable flag of the current path. void setReadOnly(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,16 +641,25 @@ 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(){ @@ -473,35 +674,50 @@ class ofFile: public fstream{ //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 +731,283 @@ 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); - /// \brief set the readable flag of the current path + /// \brief Set the readable flag of the current path. + /// + /// \param readable set to true to make path readable void setReadOnly(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 + /// \brief Open an ofFile instance using the path a given position in the + /// directory contents list. + /// + /// Opens as a text file with read only 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 true if you are working with binary data + /// (aka image, not text) + /// \returns 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 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; @@ -713,33 +1027,47 @@ class ofDirectory{ // 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; From af4004fce022059d4e7fa53ab525f27106dd5e64 Mon Sep 17 00:00:00 2001 From: danomatika Date: Sat, 5 Mar 2016 10:15:17 -0700 Subject: [PATCH 2/7] ofFileUtils: set all binary defaults to true --- libs/openFrameworks/utils/ofFileUtils.h | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index 2dc0a88e643..82096fb78db 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -217,8 +217,9 @@ class ofBuffer{ /// Opens as a text file by default. /// /// \param path file to open -/// \param binary set to true if you are reading binary data -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 +ofBuffer ofBufferFromFile(const string & path, bool binary=true); //-------------------------------------------------- /// \brief Write the contents of a buffer to a file at path. @@ -227,8 +228,8 @@ ofBuffer ofBufferFromFile(const string & path, bool binary=false); /// /// \param path file to open /// \param buffer data source to write from -/// \param binary set to true if you are writing binary data -bool ofBufferToFile(const string & path, ofBuffer & buffer, bool binary=false); +/// \param binary set to false if you are writing a text file +bool ofBufferToFile(const string & path, ofBuffer & buffer, bool binary=true); //-------------------------------------------------- /// \class ofFilePath @@ -450,19 +451,19 @@ class ofFile: public fstream{ /// \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) + /// \param binary set to false if you are reading a text file & want lines + /// split at endline characters /// \returns true if the path was opened - bool open(const std::filesystem::path & path, Mode mode=ReadOnly, bool binary=false); + 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 true if you are working with binary data - /// (aka image, not text) + /// \param binary set to false if you are reading a text file & want lines + /// split at endline characters /// \returns true if the file was reopened with the new access mode(s). - bool changeMode(Mode mode, bool binary=false); + bool changeMode(Mode mode, bool binary=true); /// \brief Close a currently open file. void close(); From 3d0b296e1cf3b8003e19040b5f59676bca29740b Mon Sep 17 00:00:00 2001 From: danomatika Date: Tue, 8 Mar 2016 11:43:01 -0700 Subject: [PATCH 3/7] ofFileUtils: replaced setReadOnly with setReadable --- libs/openFrameworks/utils/ofFileUtils.cpp | 32 +++++++++++++++-------- libs/openFrameworks/utils/ofFileUtils.h | 4 +-- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.cpp b/libs/openFrameworks/utils/ofFileUtils.cpp index 3877f7f4b71..5337dc045d4 100644 --- a/libs/openFrameworks/utils/ofFileUtils.cpp +++ b/libs/openFrameworks/utils/ofFileUtils.cpp @@ -648,30 +648,40 @@ 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(); + } } //------------------------------------------------------------------------------------------------------------ -void ofFile::setReadOnly(bool 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(); } } @@ -972,8 +982,8 @@ void ofDirectory::setWriteable(bool flag){ } //------------------------------------------------------------------------------------------------------------ -void ofDirectory::setReadOnly(bool flag){ - return ofFile(myDir,ofFile::Reference).setReadOnly(flag); +void ofDirectory::setReadable(bool flag){ + return ofFile(myDir,ofFile::Reference).setReadable(flag); } //------------------------------------------------------------------------------------------------------------ diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index 82096fb78db..bbf498c9652 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -564,7 +564,7 @@ class ofFile: public fstream{ void setWriteable(bool writeable=true); /// \brief Set the readable flag of the current path. - void setReadOnly(bool readable=true); + void setReadable(bool readable=true); /// \brief Set the executable flag of the current path. void setExecutable(bool executable=true); @@ -817,7 +817,7 @@ class ofDirectory{ /// \brief Set the readable flag of the current path. /// /// \param readable set to true to make path readable - void setReadOnly(bool readable=true); + void setReadable(bool readable=true); /// \brief Set the executable flag of the current path. /// From 23387d028c011b9b4de266a2085ab14bc4111f20 Mon Sep 17 00:00:00 2001 From: danomatika Date: Tue, 8 Mar 2016 11:49:55 -0700 Subject: [PATCH 4/7] ofFileUtils: updated commenting and set ofDirectory::getFile binary=true --- libs/openFrameworks/utils/ofFileUtils.h | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index bbf498c9652..2834ffb6234 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -218,7 +218,7 @@ class ofBuffer{ /// /// \param path file to open /// \param binary set to false if you are reading a text file & want lines -/// split at endline characters +/// split at endline characters automatically ofBuffer ofBufferFromFile(const string & path, bool binary=true); //-------------------------------------------------- @@ -228,7 +228,8 @@ ofBuffer ofBufferFromFile(const string & path, bool binary=true); /// /// \param path file to open /// \param buffer data source to write from -/// \param binary set to false if you are writing a text file +/// \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); //-------------------------------------------------- @@ -428,7 +429,8 @@ class ofFile: public fstream{ /// \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 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 @@ -452,7 +454,7 @@ class ofFile: public fstream{ /// \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 + /// 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); @@ -461,7 +463,7 @@ class ofFile: public fstream{ /// \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 + /// 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); @@ -942,7 +944,7 @@ class ofDirectory{ /// \brief Open an ofFile instance using the path a given position in the /// directory contents list. /// - /// Opens as a text file with read only access by default. + /// 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. @@ -951,10 +953,10 @@ class ofDirectory{ /// \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 true if you are working with binary data - /// (aka image, not text) + /// \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=false) const; + 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. /// From 6676a7ca743d9d976d7474c3a979fabe56da9acb Mon Sep 17 00:00:00 2001 From: danomatika Date: Tue, 8 Mar 2016 11:59:08 -0700 Subject: [PATCH 5/7] ofFileUtils: added ofFile::create(path) --- libs/openFrameworks/utils/ofFileUtils.cpp | 9 +++++++-- libs/openFrameworks/utils/ofFileUtils.h | 12 ++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.cpp b/libs/openFrameworks/utils/ofFileUtils.cpp index 5337dc045d4..9b967105190 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); } diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index 2834ffb6234..34b08b90d8f 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -471,8 +471,20 @@ class ofFile: public fstream{ void close(); /// \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(); + /// \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 From c5aa59c2df29ac856bc290628de5403ac91a7335 Mon Sep 17 00:00:00 2001 From: danomatika Date: Tue, 8 Mar 2016 12:06:50 -0700 Subject: [PATCH 6/7] ofFileUtils: fixed whitespace indentation --- libs/openFrameworks/utils/ofFileUtils.cpp | 64 +++++++++++------------ libs/openFrameworks/utils/ofFileUtils.h | 32 ++++++------ 2 files changed, 48 insertions(+), 48 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.cpp b/libs/openFrameworks/utils/ofFileUtils.cpp index 9b967105190..4c9650fb3be 100644 --- a/libs/openFrameworks/utils/ofFileUtils.cpp +++ b/libs/openFrameworks/utils/ofFileUtils.cpp @@ -914,7 +914,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)); } //------------------------------------------------------------------------------------------------------------ @@ -928,9 +928,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){ @@ -1077,9 +1077,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(); @@ -1205,18 +1205,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; } //------------------------------------------------------------------------------------------------------------ @@ -1536,24 +1536,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 34b08b90d8f..b3acd46fb15 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -103,7 +103,7 @@ class ofBuffer{ /// size, the buffer's size is increased to _size_ bytes. /// /// \param _size number of bytes to resize the buffer to - void resize(std::size_t _size); + void resize(std::size_t _size); /// \brief Access the buffer's contents using a raw byte pointer. /// @@ -160,9 +160,9 @@ class ofBuffer{ /// struct Line: public std::iterator{ Line(vector::iterator _begin, vector::iterator _end); - const string & operator*() const; - const string * operator->() const; - const string & asString() const; + const string & operator*() const; + const string * operator->() const; + const string & asString() const; /// \brief Increment to the next line. Line& operator++(); @@ -170,15 +170,15 @@ class ofBuffer{ /// \brief Increment to a number of lines. Line operator++(int); - bool operator!=(Line const& rhs) const; - bool operator==(Line const& rhs) const; + 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 @@ -189,13 +189,13 @@ class ofBuffer{ Lines(vector::iterator begin, vector::iterator end); /// \brief Get the first line in the buffer. - Line begin(); + Line begin(); /// \brief Get the last line in the buffer. Line end(); private: - vector::iterator _begin, _end; + vector::iterator _begin, _end; }; /// \brief Access the contents of the buffer as a series of text lines. @@ -681,9 +681,9 @@ class ofFile: public fstream{ return myFile; } - operator const std::filesystem::path() const{ - return myFile; - } + operator const std::filesystem::path() const{ + return myFile; + } //------- //static helpers @@ -1034,9 +1034,9 @@ class ofDirectory{ return myDir; } - operator const std::filesystem::path() const{ - return myDir; - } + operator const std::filesystem::path() const{ + return myDir; + } //------- // static helpers From 9c7fe0606650c91ba320b754a45fcd989fa8d4f8 Mon Sep 17 00:00:00 2001 From: danomatika Date: Tue, 8 Mar 2016 17:01:07 -0700 Subject: [PATCH 7/7] ofFileUtils: re-added setReadOnly with deprecated macro, updated fileUtils test to use setWriteable() instead of setReadOnly() --- libs/openFrameworks/utils/ofFileUtils.cpp | 12 ++++++++++++ libs/openFrameworks/utils/ofFileUtils.h | 4 ++++ tests/utils/fileUtils/src/main.cpp | 4 ++-- 3 files changed, 18 insertions(+), 2 deletions(-) diff --git a/libs/openFrameworks/utils/ofFileUtils.cpp b/libs/openFrameworks/utils/ofFileUtils.cpp index 4c9650fb3be..e6dc7299cd8 100644 --- a/libs/openFrameworks/utils/ofFileUtils.cpp +++ b/libs/openFrameworks/utils/ofFileUtils.cpp @@ -664,6 +664,12 @@ void ofFile::setWriteable(bool flag){ } } +//------------------------------------------------------------------------------------------------------------ +// deprecated +void ofFile::setReadOnly(bool flag){ + setWriteable(!flag); +} + //------------------------------------------------------------------------------------------------------------ void ofFile::setReadable(bool flag){ try{ @@ -986,6 +992,12 @@ void ofDirectory::setWriteable(bool flag){ return ofFile(myDir,ofFile::Reference).setWriteable(flag); } +//------------------------------------------------------------------------------------------------------------ +// deprecated +void ofDirectory::setReadOnly(bool flag){ + setWriteable(!flag); +} + //------------------------------------------------------------------------------------------------------------ void ofDirectory::setReadable(bool flag){ return ofFile(myDir,ofFile::Reference).setReadable(flag); diff --git a/libs/openFrameworks/utils/ofFileUtils.h b/libs/openFrameworks/utils/ofFileUtils.h index b3acd46fb15..13244db33c0 100644 --- a/libs/openFrameworks/utils/ofFileUtils.h +++ b/libs/openFrameworks/utils/ofFileUtils.h @@ -576,6 +576,8 @@ class ofFile: public fstream{ /// \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 setReadable(bool readable=true); @@ -827,6 +829,8 @@ class ofDirectory{ /// /// \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. /// 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");