Cross-Platform C++

ot::io
class File

#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:

  1. 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
  2. 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:-

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

Method Detail

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: -
  1. isolates the prefix, which remains static
  2. removes "/." sequences
  3. 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< StringlistDirectory() 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


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements