#include "ot/io/File.h"
A system-independent representation of file and directory names.
Different operating systems employ various conventions for the naming of files and directories. This class presents an abstract, system-independent view of file and directory pathnames, together with convenient methods for manipulating them.
An abstract pathname has two components:
-
An optional system-dependent prefix string, such as a DOS disk-drive identifier, the UNIX root directory name /, or the Windows Universal Naming Convention (UNC) prefix \\host\share\ ; and
-
A sequence of zero or more string names representing the hierarchical directory structure
Each name in an abstract pathname except for the last denotes a directory; the last name may denote either a directory or a file.
This class provides the means to convert from a system-dependent pathname into a system-independent abstract pathname. This is achieved by splitting the string into a sequence of tokens separated by the system-specific name separator character which can be obtained using the static method GetSeparatorChar().
A pathname may be either absolute or relative. An absolute pathname can be used to locate the file or directory which it denotes without the need for any other information. A relative pathname, in contrast, must be interpreted in terms of some other absolute pathname.
Relative pathnames are resolved against the system's current directory which can be obtained using the static method GetCurrentDirectory().
Whether or not an abstract pathname is relative depends on the optional prefix string. It is interpreted as follows:-
-
For UNIX platforms, the prefix of an absolute pathname is always /. Relative pathnames have no prefix. The abstract pathname denoting the root directory has the prefix / and an empty name sequence.
-
For Windows platforms, the prefix of a pathname that contains a drive specifier consists of the drive letter followed by ":" and possibly followed by \ if the pathname is absolute. The prefix of a UNC pathname is \\<host>\<share>\. UNC names are always absolute.
The concept of a prefix and name sequence is an internal abstraction; these separate components are not exposed in any interfaces.
Instances of the File class are immutable; that is, once created, the abstract pathname represented by a File object will never change.
The File class is a simple value-type class. It is not reference-counted and can be passed by value or by reference.
Constructor/Destructor Summary |
File(const String& pathname)
Constructs a File from a pathname string. |
File(const File& rhs)
Constructs a File from another abstract pathname. |
File(const File& parent, const String& child)
Constructs a File using a parent pathname string and a child pathname string. |
File(const String& parent, const String& child)
Constructs a File using a parent pathname string and a child pathname string. |
Method Summary
|
bool |
canRead() const
Tests to see if the file denoted by this abstract filename is readable. |
bool |
canWrite() const
Tests to see if the file denoted by this abstract pathname is writable. |
void |
createNewFile() const
Creates a new file on the underlying file system. |
void |
deleteFile() const
Deletes the file. |
bool |
exists() const
Tests to see if the file exists. |
String |
getAbsolutePath() const
Returns the absolute pathname string of this abstract pathname. |
String |
getCanonicalPath() const
Returns the canonical path for the abstract pathname denoted by this File. |
static String |
GetCanonicalPath(const String& path)
Static function that performs a basic canonicalization algorithm to reduce an absolute pathname to its shortest form. |
static String |
GetCurrentDirectory()
Returns the current working directory as reported by the underlying operating system. |
String |
getName() const
Returns the name denoted by the abstract pathname of this file or directory. |
String |
getParent() const
Returns the pathname string denoting the parent directory of this abstract pathname, or the empty string if this does not name a parent directory. |
File |
getParentFile() const
Returns a File representing the abstract pathname denoting the parent directory of this abstract pathname. |
String |
getPath() const
Returns the abstract pathname as a string. |
static String |
GetSeparator()
Returns the system-dependent filename separator character as a String with a length of 1. |
static CharType |
GetSeparatorChar()
Returns the system-dependent filename separator character. |
bool |
isAbsolute() const
Tests whether the abstract pathname denotes an absolute pathname. |
bool |
isDirectory() const
Tests to see if the file denoted by this abstract pathname is a directory. |
bool |
isFile() const
Tests to see if the file denoted by this abstract pathname is a file. |
DateTime |
lastModified() const
Returns the DateTime that the file was last modified. |
size_t |
length() const
Returns the length in Bytes of the file denoted by this abstract pathname. |
std::list< String > |
listDirectory() const
Returns a list of names of the files and directories contained in the directory denoted by this abstract pathname. |
void |
mkdir() const
Creates a directory with the name of this abstract pathname. |
void |
mkdirs() const
Creates a directory with the name of this abstract pathname. |
bool |
operator!=(const File& rhs) const
Tests to see if this abstract pathname represents a different file or directory from the abstract pathname rhs. |
bool |
operator==(const File& rhs) const
Tests to see if this abstract pathname represents the same file or directory as the abstract pathname rhs. |
void |
renameTo(const File& file) const
Renames the file denoted by the abstract pathname to the abstract pathname file. |
void |
setLastModified(const DateTime& time) const
Sets the date and time the file was last modified to time. |
void |
setReadOnly(bool bReadOnly) const
Updates the file's security permission flags. |
Constructor/Destructor Detail |
File
File(const String& pathname)
-
Constructs a File from a pathname string.
The pathname may be relative or absolute. If, subsequent to construction, member functions such as canRead() are called, relative abstract pathnames are resolved into absolute pathnames by combining the pathname with the current working directory.
- Parameters:
pathname
-
a relative or absolute pathname
File
File(const File& rhs)
-
Constructs a File from another abstract pathname.
- Parameters:
rhs
-
the abstract pathname
File
File(const File& parent,
const String& child)
-
Constructs a File using a parent pathname string and a child pathname string.
Create an abstract pathname by resolving the child in relation to the parent. If the parent represents an empty abstract pathname then it is substituted with "/" which, on UNIX platforms represents the absolute root filename but under Windows this represents the root directory of the current drive.
If you wish to resolve a relative pathname against the current working directory then you should use the File(const String& name) constructor or pass the value returned from GetCurrentDirectory() as the parent.
- Parameters:
parent
-
the parent abstract pathname
child
-
the child pathname string
File
File(const String& parent,
const String& child)
-
Constructs a File using a parent pathname string and a child pathname string.
The parent pathname is treated as if it were a directory, even if it is not one. If the parent pathname is empty then it is substituted with "/" which, on UNIX platforms represents the absolute root filename but under Windows this represents the root directory of the current drive.
If you wish to resolve a relative pathname against the current working directory then you should use the File(const String& name) constructor or pass the value returned from GetCurrentDirectory() as the parent.
- Parameters:
parent
-
the parent abstract pathname
child
-
the child pathname string
canRead
bool canRead() const
-
Tests to see if the file denoted by this abstract filename is readable.
This resolves the abstract filename and uses it to probe the file system to see if a file with that name exists and, if so, whether it's permission flags allow it to be read by the current process.
- Returns:
-
true if the file exists and is readable; false otherwise
canWrite
bool canWrite() const
-
Tests to see if the file denoted by this abstract pathname is writable.
This resolves the abstract filename and uses it to probe the file system to see if a file with that name exists and, if so, whether it's permission flags allow it to be written to by the current process.
- Returns:
-
true if the file exists and is writable; false otherwise
createNewFile
void createNewFile() const
-
Creates a new file on the underlying file system.
This function tests for the existence of the file and creates the file in a single atomic operation. Because the test and the creation are performed in a single operation, it is possible to use this to create lock files.
- Exceptions:
IOException
-
if an error occurs while creating the file
ExistingFileException
-
if the file already exists
deleteFile
void deleteFile() const
-
Deletes the file.
This resolves the abstract filename and uses it to request that the underlying file system deletes the file.
- Returns:
-
true if the file was deleted, false otherwise.
- Exceptions:
FileNotFoundException
-
if a file with this abstract pathname does not exist
IOException
-
if an error occurs while deleting the file.
exists
bool exists() const
-
Tests to see if the file exists.
This resolves the abstract filename and uses it to probe the file system to see if a file with that name exists.
- Returns:
-
true if the file exists.
getAbsolutePath
String getAbsolutePath() const
-
Returns the absolute pathname string of this abstract pathname.
If the abstract pathname is already absolute (which can be determined by calling isAbsolute()), then this method simply returns the pathname as if by calling getPath(). Otherwise the abstract pathname is resolved against the current working directory using GetCurrentDirectory() on this class.
- Returns:
-
the absolute pathname string of this abstract pathname.
- Exceptions:
IOException
-
if an error occurs while getting the current working directory.
getCanonicalPath
String getCanonicalPath() const
-
Returns the canonical path for the abstract pathname denoted by this File.
The canonical path is system dependent, but is always absolute and generally the shortest means of expressing a file name.
If this File denotes a relative abstract filename, then it is first made absolute by calling getAbsolutePath().
The canonical path of an existing file may differ to the canonical path of an abstract pathname that doesn't exist because the underlying operating system (esp. Windows) may change the case or absolute location of an existing file.
- Returns:
-
the current canonical path as a string.
- Exceptions:
IOException
-
if an error occurs while obtaining the current working directory.
GetCanonicalPath
static String GetCanonicalPath(const String& path)
-
Static function that performs a basic canonicalization algorithm to reduce an absolute pathname to its shortest form.
The algorithm involves the following steps: -
-
isolates the prefix, which remains static
-
removes "/." sequences
-
removes "<dir>/.." sequences
This function does not perform case-folding on case-insensitive file systems such as Windows. Use the non-static version of getCanonicalPath() for that.
- Parameters:
path
-
the pathname to be canonicalized
- Returns:
-
a canonical representation of the input pathname
- See also:
-
getCanonicalPath()
GetCurrentDirectory
static String GetCurrentDirectory()
-
Returns the current working directory as reported by the underlying operating system.
- Returns:
-
the current working directory.
- Exceptions:
IOException
-
if an error occurs while fetching the current working directory.
getName
String getName() const
-
Returns the name denoted by the abstract pathname of this file or directory.
The name is the last part of the name sequence, separated from the rest of the path by the final filename separator character.
The filename separator character can be obtained using the static GetSeparatorChar() function or, in string form, using GetSeparator().
If the abstract pathname is empty, or consists only of a prefix, then the empty string is returned.
- Returns:
-
the name of the file or directory.
getParent
String getParent() const
-
Returns the pathname string denoting the parent directory of this abstract pathname, or the empty string if this does not name a parent directory.
The parent consists of the prefix (if any) followed by all names from the sequence except the last (which is called the file name and may be obtained using the getName() method).
If the name sequence is contains only one name, then this abstract pathname does not name a parent.
- Returns:
-
the pathname string denoting the parent of this abstract pathname.
- See also:
-
getParentFile()
getParentFile
File getParentFile() const
-
Returns a File representing the abstract pathname denoting the parent directory of this abstract pathname.
- Returns:
-
a File object representing the abstract pathname denoting the parent directory
- See also:
-
getParent()
getPath
String getPath() const
-
Returns the abstract pathname as a string.
- Returns:
-
the abstract pathname as a string.
GetSeparator
static String GetSeparator()
-
Returns the system-dependent filename separator character as a String with a length of 1.
On Windows-based platforms this is "\" and on Unix platforms it is "/".
- Returns:
-
the system-dependent filename separator character as a String
GetSeparatorChar
static CharType GetSeparatorChar()
-
Returns the system-dependent filename separator character.
On Windows-based platforms this is '\' and on Unix platforms it is '/'.
- Returns:
-
the system-dependent filename separator character
isAbsolute
bool isAbsolute() const
-
Tests whether the abstract pathname denotes an absolute pathname.
An absolute pathname does not require any additional context information for the operating system to resolve into a physical file. Conversely, a relative pathname needs to be resolved against an absolute pathname before it can be used to access a file.
The definition of an absolute pathname is system-dependent. On UNIX platforms a pathname is absolute if is has a leading "/". On Windows platforms it is absolute if a drive letter and "\" are specified, or it is a UNC name.
- Returns:
-
true if the abstract pathname denotes an absolute pathname; false otherwise.
isDirectory
bool isDirectory() const
-
Tests to see if the file denoted by this abstract pathname is a directory.
This resolves the abstract filename and uses it to probe the file system to see if a file with that name exists and, if so, whether it is a directory.
- Returns:
-
true if the file exists and is a directory; false otherwise
isFile
bool isFile() const
-
Tests to see if the file denoted by this abstract pathname is a file.
This resolves the abstract filename and uses it to probe the file system to see if a file with that name exists and, if so, whether it is a regular file.
- Returns:
-
true if the file exists and is a file; false otherwise
- See also:
-
isDirectory()
lastModified
DateTime lastModified() const
-
Returns the DateTime that the file was last modified.
- Returns:
-
the DateTime that the file was last modified
- Exceptions:
IOException
-
if an error occurs while obtaining the last modified DateTime
FileNotFoundException
-
if a file with this abstract pathname does not exist
length
size_t length() const
-
Returns the length in Bytes of the file denoted by this abstract pathname.
This resolves the abstract filename and uses it to probe the file system to see if a file with that name exists and, if so, obtains its size.
- Returns:
-
the size of the file.
- Exceptions:
IOException
-
if an error occurs while probing the file.
FileNotFoundException
-
if the file does not exist
listDirectory
std::list< String > listDirectory() const
-
Returns a list of names of the files and directories contained in the directory denoted by this abstract pathname.
If this abstract pathname does not denote a directory (which can be determined by calling the isDirectory() member function on this class) then an empty list is returned.
- Returns:
-
a list of strings of file and directory names.
- Exceptions:
IOException
-
if an error occurs while listing the file names.
mkdir
void mkdir() const
-
Creates a directory with the name of this abstract pathname.
- Exceptions:
IOException
-
if an unexpected error occurs while attempting to create the directory or the directory already exists.
FileNotFoundException
-
if any part of the pathname sequence except for the last does not exist
mkdirs
void mkdirs() const
-
Creates a directory with the name of this abstract pathname.
If any of the parent directories do not already exist, this function will attempt to create these also.
- Exceptions:
IOException
-
if an error occurs while attempting to create directories or the directory already exists
- See also:
-
mkdir()
operator!=
bool operator!=(const File& rhs) const
-
Tests to see if this abstract pathname represents a different file or directory from the abstract pathname rhs.
The test is case-insensitive on systems that do not have a case-sensitive file system (e.g. Windows). Before comparing the abstract pathnames, they are first made absolute by calling getCanonicalPath().
- Parameters:
rhs
-
the abstract pathname to be compared
- Returns:
-
true if the abstract pathname is not the same; false otherwise
- Exceptions:
IOException
-
is an error occurs obtaining the canonical path
- See also:
-
operator==()
operator==
bool operator==(const File& rhs) const
-
Tests to see if this abstract pathname represents the same file or directory as the abstract pathname rhs.
The test is case-insensitive on systems that do not have a case-sensitive file system (e.g. Windows). Before comparing the abstract pathnames, they are first made absolute by calling getCanonicalPath().
- Parameters:
rhs
-
the abstract pathname to be compared
- Returns:
-
true if the abstract pathname is the same; otherwise false.
- Exceptions:
IOException
-
is an error occurs obtaining the canonical path
- See also:
-
operator!=()
renameTo
void renameTo(const File& file) const
-
Renames the file denoted by the abstract pathname to the abstract pathname file.
- Parameters:
file
-
new abstract pathname
- Returns:
-
true if the file was renamed; false otherwise
- Exceptions:
IOException
-
if an error occurs while renaming the file.
FileNotFoundException
-
if a file with this abstract pathname does not exist or if any part of the new pathname sequence does not exist
setLastModified
void setLastModified(const DateTime& time) const
-
Sets the date and time the file was last modified to time.
On some platforms the file system does not support the full resolution provided by the DateTime class. In this case the time is truncated to the most precise value that is supported.
- Parameters:
time
-
the date and time value to set
- Exceptions:
IOException
-
if an error occurs while setting the modified DateTime
FileNotFoundException
-
if a file with this abstract pathname does not exist
setReadOnly
void setReadOnly(bool bReadOnly) const
-
Updates the file's security permission flags.
On Unix platforms, when setting the file to writable, only the 'user' permission flags are updated - the file's 'group' and 'other' permission flags are untouched.
- Parameters:
bReadOnly
-
set to true to make the file read only, false to make it writable
- Exceptions:
IOException
-
if an error occurs while setting the file's permission flags
FileNotFoundException
-
if a file with this abstract pathname does not exist
Found a bug or missing feature? Please email us at support@elcel.com