| Index |
This class offers a set of low and high-level operations for safe and convenient handling of directories or conventional files including common operations like reading, writing, copying, removing, existence and difference checking and so forth. More...
#include "universal__File.h"
| FS_LOCAL | = | 0 | |
| FS_UNIX | = | 1 | |
| FS_WINDOWS | = | 2 | |
| FS_MAC | = | 3 |
This class offers a set of low and high-level operations for safe and convenient handling of directories or conventional files including common operations like reading, writing, copying, removing, existence and difference checking and so forth.
Conventional files are handled as raw streams of bytes which can be randomly accessed. Sometimes high-level string objects can be passed as input to or/and returned as result of a function.
The term "file" is used throughout the API and documentation to refer both to directories or conventional files.
This class is designed for high performance and relies directly upon the C file stream API (FILE*, fwrite(), fread()...).
Finds files of the specified name patterns inside the given directory paths.
bRecurse is optional and true by default. It tells whether to recurse into sub-directories to find files matching the passed name pattern.
See also:
Tells whether the passed file path is an absolute path.
See also:
Checks whether the passed file exists. Returns true if so.
See also:
Creates a new path resulting from the concatenation of path1, a file separator and path2.
Ensures the new path is stripped of all superfluous leading and trailing chars using stripFileName().
See also:
Identical to join().
See also:
Returns the current working directory path.
If the current working directory could not be determined, an empty string is returned. This can happen if the current directory has been removed during the process running.
See also:
Reads the content of the specified file path.
If any failure was encounted (eg. unexistent file), an empty string is returned.
See also:
Creates the file of the specified path and set its content to c_sContent.
c_sContent is optional and empty by default. Therefore, calling this method with only the first argument will create an empty file.
If the file could not be created, false is returned and true otherwise.
See also:
If c_pszSrc is an existing conventional file, c_pszSrc is copied to file c_pszDst. If c_pszDst is an existing directory, c_pszSrc is simply duplicated inside directory c_pszDst. Conventional files are copied by block of 512 Ko.
If c_pszSrc is an existing directory, the whole directory and its content are recursively copied to c_pszDst. Note that if c_pszDst was already existing, the copy consists of duplicating the content of the source directory into the destination directory. To actually duplicate c_pszSrc inside an existing target directory, the target directory path should be suffixed with ".".
bOverwrite tells whether to overwrite files during copy. When directories are copied, the flag is just forwarded to the copy function calls performed for the content files. bOverwrite is optional and by default nothing is overwritten.
Returns true if the operation was successful and the file was written or overwritten.
Returns false otherwise, i.e. source file or directory does not exist or c_pszDst is not a valid target directory. If a target file was existing while overwriting was not allowed (bOverwrite == false), errno is additionally set to EEXIST. If a source or target file couldn't be open errno is set to EINVAL. If there was a write error, errno is set to EIO.
To explain how directory copying works, let suppose we have the following source directory (UNIX file system):
Example:
source/: total 16 -rw-rw-r-- 1 mehl mehl 50 Jul 15 11:31 file.txt -rw-rw-r-- 1 mehl mehl 30 Jul 15 11:31 otherfile.txt drwxrwxr-x 2 mehl mehl 4096 Jul 15 11:31 subdir source/subdir: total 4 -rw-rw-r-- 1 mehl mehl 123 Jul 15 11:31 readme.txt
The copy instruction
File::copy("source", "destination") would result in the following:Example:
destination/: total 16 -rw-rw-r-- 1 mehl mehl 50 Jul 15 11:34 file.txt -rw-rw-r-- 1 mehl mehl 30 Jul 15 11:34 otherfile.txt drwxrwxr-x 2 mehl mehl 4096 Jul 15 11:34 subdir destination/subdir: total 4 -rw-rw-r-- 1 mehl mehl 123 Jul 15 11:34 readme.txt
Now, calling again
File::copy("source", "destination") would not have any additional effect, because the source directory is not created inside the now existing destination directory, but rather its content is copied inside there.See also:
Tells whether file c_pszFile1 and file c_pszFile2 differ.
If the files are conventional files, their content is compared with each other. The content of files are read and checked by block of 512 Ko.
If the files are directories, their file content is compared with each other recursively. That means, there must be exactly the same files there and their content must be equal.
Returns also true if any read error was encountered during the diff.
See also:
Returns by default the separator used in file paths on the current platform/filesystem.
fs_category is an optional parameter which allows to specify explicitely the platform/file system category for which the separator is requested.
See also:
Filters the passed file list according to the given list of name patterns which must be separated by comas.
Returns the number of files removed from the passed list files.
See also:
Allows to change directory to sDir.
See also:
Allows to change directory to sDir.
See also:
Constructor.
c_sFileName gives the name of the directory or the file. The name can be a base name, a relative path or an absolute path.
If c_sFileName is a file, the constructor will attempt to open the file according to the opening mode sMode.
sMode give the mode. It is the same string that the one passed to the C FILE stream function ::fopen(...);
sMode is optional. By default, it is set to "r" (read-only).
As remainder, the possible modes are the following:
r Open text file for reading. The stream is positioned at the beginning of the file.
r+ Open for reading and writing. The stream is positioned at the beginning of the file.
w Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file.
w+ Open for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file.
a Open for writing. The file is created if it does not exist. The stream is positioned at the end of the file.
a+ Open for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file.
bDoOpen tells whether to attempt to open the file immediately. bDoOpen is optional. By default, it is set to "true" (do open the file with the specified mode).
See also:
Constructor.
Creates a file object pointing to nothing.
The default access mode is read-only.
The file is not open. It can be open afterwards using open().
Under UNIX, it is equivalent to constructing a file object with File("/dev/null", "r", false); Under Windows, there is no equivalent to the /dev/null device. The matching file object is constructed with File("", "r", false).
See also:
Destructor.
See also:
Sets the name of the file without changing access mode.
The new file is not open. It can be open afterwards using open().
Any failure is cleared and the previous file is closed if it was open.
See also:
Sets or changes the extension of the file. The new extension must be provided WITHOUT the dot.
See also:
Overloaded function provided for convenience. Does the same as the previous function.
See also:
Tells whether the file exists.
See also:
Tells whether the file is actually a directory.
See also:
Tells whether the file is the root directory. On UNIX, root directory is '/'. On Windows, root directory is either '\\' or a letter drive like 'C:'.
See also:
Tells whether the file is the null directory. On UNIX, null directory is '/dev/null'. On Windows, null directory is "".
See also:
Clears the failure flag to allow to execute further actions on the file.
See also:
Tells whether a failure occurred while opening, reading, writing or removing.
See also:
Tells whether EOF was encountered.
See also:
Sets the failure flag.
See also:
In case of a failure, this allows to get the error message. This is the string as returned by the system function ::strerror(int).
See also:
Removes the file or directory from file system.
Any conventional file which is open is closed prior to the removal.
An attempt to remove a non-empty directory will fail. To remove a directory and all its content, the bRecurse parameter must be set to true.
By default, the function does not recurse the removal process in all sub directories if the file is a directory. For doing so, the optional parameter bRecurse should be set to true.
See also:
Synonym for remove and defined for convenience.
See also:
Opens the file with the specified mode.
See also:
Tells whether the file is open.
See also:
Returns the name of the file as passed to the constructor.
See also:
Returns the base name of the file path passed to the constructor, also called the tail of the initial file path.
bWithoutExtension is optional and set to false by default. It tells whether to return the base name without the file extension.
See also:
Example:
File f("/home/mehl");
String s = f.basename(); // s == "mehl"
File f2("/home/mehl/.bashrc");
String s2 = f2.basename(); // s == ".bashrc"Returns the extension of the file or an empty string if none.
The dot is not part of the returned string.
If the file name starts with a dot, the chars following this dot are NOT considered as a file extension.
Example:
File f("/home/mehl/planet.png");
String s = f.extension(); // s == "png"See also:
Returns a string uniquely identifying the hard drive on which is located this file. This operation may require super-user priviledges and this function may set the failure flag and failure error message.
See also:
Returns the path of the device on which is located this file.
See also:
Looks up the absolute path of the file in the environment, assuming this object refers to an executed file. This path resolution process is the following:
- If the file name is already an absolute path, return it as is
- If the file name is a relative path, reconstitue the path by appending this relative path to the absolute path of the current working directory.
- Otherwise, scan the PATH environnment variable and ckeck that the absolute path of the executed file can be resolved from one of the paths defined by the PATH environement variable.
- If no absolute file could be, the absolute path of the file as returned the following function is returned.
See also:
Returns the absolute path of the file, assuming its name or path was given relative to the current working directory.
If the file name is already an absolute path, it is returned as is.
See also:
Returns the path of this file relatively to c_sOtherFile, assuming this latter is an absolute path.
See also:
Returns the file object standing for the (parent) directory of this file.
See also:
Finds the ancestor directory common to c_f and this file. If no common ancestor could be found (only happens on Windows normally), a null File object is returned, i.e isNull() returns true for this object.
See also:
Expands all symbolic links and resolves references to characters '/./' '/../' and extra '/' chars.
See also:
Returns the DOS short name. Under UNIX, just returns the name of the file.
See also:
Returns true if the creation if the full path was successful.
Returns false if any component of the path couldn't be created; In that case, the directory may only be partially created.
Under UNIX, the permissions assigned to the created directory is rwxr-xr-x.
bForce is optional and false by default. It is useful to handle the case where a component of the directory path to create is found to be an existing plain file (not a directory). This parameter tells whether to remove this file and replace it with a directory of the same name.
See also:
Change current directory to this directory.
Returns true on success.
See also:
Returns the current position in the file. Returns -1 if the file is not open.
See also:
Returns the size in byte of the file, or -1 if this size couldn't be determined. This data is cached in an internal variable.
See also:
Writes the passed string to the file and appends a new line char.
See also:
Writes the passed string to the file.
See also:
Writes uLen bytes from offset uOffset of the passed buffer c_pucBytes.
Returns the number of bytes written.
See also:
Flushes any buffered written data.
Returns true on success. Otherwise the failure flag and error message is set.
See also:
Purges any buffered input or output data.
This operation is actually not supported yet ! Returns always false.
Returns true on success. Otherwise the failure flag and error message is set.
See also:
Reads uSize bytes from the current position and puts them from offset uOffset in the passed byte buffer pucBytes.
Returns the number of bytes read or -1 on error.
See also:
Reads exactly one byte from the file. If a failure occurred 0 is returned and fail() returns true.
See also:
Closes the file. Called from the destructor.
See also:
Prints the content of the file to the standard output. This is performed regardless of the current file status (open or not, failure or not...).
Returns a boolean telling whether any failure occurred (the file can't be open or read).
Calling this function is equivalent to calling:
Example:
cat(std::cout)
See also:
Equivalent to the conventional cat() function, except that the output is redirected to the specified stream and not to the standard output.
Returns a boolean telling whether any failure occurred (the file can't be open or read).
See also:
Equivalent to the conventional cat() function, except that the output is appended to the specified string and not to the standard output.
Returns a boolean telling whether any failure occurred (the file can't be open or read).
See also:
Reads as many bytes as possible till to encounter a new line char in the file.
This function is Windows-compatible : special new lines chars are ignored.
Returns a string containing the read chars with or without the new line char according to the optional bWithNewLine parameter value. By default, the new line char is not included within the read line.
See also:
Reads iSize bytes from the current position in the file. If iSize is negative (default value), all the bytes till the end of file are read. The read bytes are put to the passed string.
Returns the number of bytes read or -1 on error.
See also:
Sets the position from the beginning of the file at which the next read or write occurs. The seek function allows the file offset to be set beyond the end of the existing end-of-file of the file. If data is later written at this point, subsequent reads of the data in the gap return bytes of zeros (until data is actually written into the gap).
See also:
Moves of iOffset byte(s) the current position in the file at which the next read or write occurs
See also:
Shifts the content of the file of iByteOffset bytes. If the content is moved beyond the EOF, the file will grow up of byteOffset bytes. The first byteOffset bytes of the file will be set to 0. After the shift, the file pointer is pointing to the same data as before the shift. If the file pointer was initiallly located before the shifted data, it is repositioned at this location. Otherwise, it will move of iByteOffset.
If the content is moved toward the beginning of the file, the first byteOffset will be lost and the trailing byteOffset bytes set to 0. After the shift, the file pointer will point to the same data as before the shift, but only it is not part of the lost data. In this case, the pointer is positioned at the beginning of the file. If the file pointer was initiallly located on the shifted file area, it will move back of iByteOffset. Otherwise, it will be unchanged.
Returns false if the file opening mode is incompatible with this operation, i.e. if mode is either "w", "r" or "a".
See also:
This function is provided. It behaves like the referred to function below, the except that the start position of the shift is the current position.
See also:
Fills the file with the passed char from the current position
Returns a pointer on itself.
See also:
Inserts the string sBuf at the given file position. The initial content of the file starting at this position is shifted from the number of bytes of the string, using the shift() function.
See also:
Finds recursively all files that matches any of the file name patterns given in c_sNamePatternList.
bRecurse is optional and true by default. It tells whether to recurse into sub-directories to find files matching the passed name pattern.
See also:
Lists the files of the directory, exclusive the . and .. navigation directories.
The names are filtered according to the c_sNamePatternList list of patterns. Patterns shall be separated by comas. This parameter is optional and by default, all files are listed.
bFilesOnly tells whether only conventional files should be listed. This parameter is optional and by default, only conventional files are listed. If set to false, all files inclusive directories are listed.
The returned File objects do not open the file. Users may want to open the file afterwards for further processing.
If the file is a conventional file, the returned vector is empty and the failure flag is set.
See also:
Lists the directories only.
This function first calls listFiles() and filters then the list for keeping directories only.
See also:
Lists all files regardless of file type.
This function is provided for convenience. It is the strict equivalent to listFiles(c_sNamePatternList, false)
See also:
Returns the name of the file when casted to a string.
See also:
Returns a file object pointing to the directory designated for temporary files.
On UNIX, it will generally be /tmp. On Windows, it will depend on the drive and directory the system is installed on.
On error, errno is set (all platforms).
See also:
Creates a unique temporary files and returns a file object pointing to that file.
On failure, i.e. if the file could not be created, the returned file object points to the temporary directory and errno is set.
On success, the returned file object is created with "w" (write) mode BUT the file is NOT open. To write into the file, the caller has to call the open() function on the returned file.
By default, the file is created under the standard directory designated for temporary files.
c_sTempSubDir is optional and allows to specifiy additionally the sub-directory within the standard temporary directory where the temporary should be created. If the sub-directory could not be created for any reasons, it is simply ignored and the function behaves as if this parameter was not specified.
c_sPrefix is the prefix for the temporary file name. Depending on the platform, a specific suffix is appended to this string in order to build a unique temporary file name.
On Windows, the temp. files have the following format: path\preuuuu.TMP On UNIX, the temp. files have the following format: path\preuuuu.TMP
See also:
Tells whether the file is a c plus plus header file. This checks simply whether the file extension is either *.h, *.hxx, *.hpp" (regardless of case).
See also:
Tells whether the file is a c plus plus implementation file. This checks simply whether the file extension is either *.c, *.cxx, *.cpp" (regardless of case).
See also:
Tells whether the file is a java implementation file. This checks simply whether the file extension is either java (regardless of case).
See also:
Suppress leading "./" or ".\" and trailing separators from the passed file name.
The type of separator used is the one specified by fs_category. By default, it is the separator used on the current file system.
See also: